yascha / matic-docs

Polygon PoS documentation

Matic Documentation

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

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

How to contribute to our documentation

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

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 in the past, 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 dependencies

   yarn install
   

7. Run docs 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 docs 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 good knowledge 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, 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 to 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

Make changes using our docs 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 channges to submit your changes. Note that submitting a change will write it to a new branch in your fork.

We will review your PR and either accept it or submit our review on it. 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