alireza-gsh/matic-docs

Polygon PoS documentation

Polygon Documentation

Previously Matic Network

Polygon is a scaling solution for public blockchains that combines the best of Ethereum and sovereign blockchains to offer a full-stack scaling solution.

The Polygon documentation website is built using Docusaurus, a modern static website generator.

How to Contribute to Polygon Documentation

We believe one of the things that makes Polygon unique is its coherent design, and we seek to retain this defining characteristic. We have defined some guidelines to ensure new contributions only ever enhance the documentation from the outset.

Requirements

• Install Node.js version >= 12.13
• Install Yarn version >= 1.5

Note that on macOS you also need Xcode and Command Line Tools.

Run the documentation locally

1. Fork the repo.

   For help, refer to GitHub Docs: Fork a repo.

2. Clone your forked repo.

   git clone [email protected]:[your_github_handle]/matic-docs
   

3. Navigate into the cloned folder.

   cd matic-docs
   

4. Link your cloned repo to the upstream repo.

   For help, see GitHub Docs: Configuring a remote for a fork.

   git remote add upstream https://github.com/maticnetwork/matic-docs
   

5. If you have already cloned the repository, be sure to sync your fork with the latest changes.

   For help, refer to GitHub Docs: Syncing a fork.

   git checkout master
   git fetch upstream
   git merge upstream/master
   

6. Install the dependencies.

   yarn install
   

7. Run the documentation locally. The following command will start a local development server and open a browser window. Most changes are reflected live without having to restart the server.

   yarn start
   

Make changes using Git GUI and code editor

After running the documentation locally on your machine, use a code editor to apply your changes before submitting your PR. Note that you must have a GitHub account and an understanding of Markdown syntax.

1. Create a new branch for your changes.

   git checkout -b [new_branch_name]
   

2. Commit your changes. Please be sure to review our Git Rules. In the commit message, please reference the issue it resolves. For help, see GitHub Docs: Linking a pull request to an issue using a keyword.

   git commit -m "brief description of changes [Fixes #1234]"
   

3. Push to your forked repository.

   git push
   

4. Submit a PR against the master branch of the maticnetwork/matic-docs repo

5. Add a title to your PR.

   For example, if you want to suggest edits to the "Getting Started" page, name your PR: Update /docs/develop/getting-started.md.

6. Add a description to your PR. Please reference the issue it resolves.

   For help, see GitHub Docs: Linking a pull request to an issue using a keyword.

7. Write a brief description of the changes you have made. If possible, include screenshots and references.

You can apply UI changes, sidebar, and configuration design through the following files:

• To modify the Sidebar navigation, edit sidebars.js
• To modify the website page layout, edit docusaurus.config.js
• To modify the blocks structure and the footer links, edit src/pages/index.js

Making changes using the documentation website

You can easily submit an edit suggestion. Note that you must have a GitHub account and good knowledge of Markdown syntax.

1. Navigate to the Polygon documentation page that you want to edit
2. Scroll down until the end of that page
3. Click on the link: Edit this page. It will forward you to the same page (Markdown format) hosted on GitHub.
4. On the related GitHub page, click the pencil icon (similar to ) near the upper right corner of the file
5. Apply your edits by modifying the Markdown file
6. After you finish, scroll down until the end of that page to create a pull request
7. Add a title to your PR. For example, if you want to suggest edits to the "Getting Started" page, name your PR: Update /docs/develop/getting-started.md.
8. Add a description to your PR. Please reference the issue it resolves.

   For help, see GitHub Docs: Linking a pull request to an issue using a keyword.

9. Write a brief description of the changes you have made. If possible, include screenshots and references.
10. Click on the green button Propose changes to submit your changes. Note that submitting a change will write it to a new branch in your fork.

One of the documentation maintainers will review your PR and either accept it or submit our review. Acceptable PRs will be approved & merged into the master branch.

Submit an Issue

• Create a new issue to report a bug, request a feature, or suggest changes.
• Comment on the issue if you want to be assigned to it so our team can assign the issue to you.
• If you do not have a specific contribution in mind, you can also browse current issues.
• Issues that additionally have the good first issue label are considered ideal for first-timers.

Build

This command generates static content into the build directory and can be served using any static content hosting service:

yarn build

Deployment

If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the gh-pages branch.

GIT_USER=[your_github_handle] USE_SSH=true yarn deploy