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 Wiki is built using Docusaurus, a modern static website generator to build optimized websites quickly.
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 Wiki from the outset.
Note that on macOS you also need Xcode and Command Line Tools.
-
Fork the repo.
For help, refer to GitHub Docs: Fork a repo.
-
Clone your forked repo.
git clone git@github.com:[your_github_handle]/matic-docs
-
Navigate into the cloned folder.
cd matic-docs
-
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
-
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
-
Install the dependencies.
yarn install
The site is built using Docusaurus. You may need to install Docusaurus before running the Wiki locally.
yarn add docusaurus
Alternatively, you can upgrade Docusaurus.
yarn upgrade @docusaurus/core@latest @docusaurus/preset-classic@latest
-
Run the Wiki 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
After running the Wiki 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.
-
Create a new branch for your changes.
git checkout -b [new_branch_name]
-
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]"
-
Push to your forked repository.
git push
-
Submit a PR against the
master
branch of thematicnetwork/matic-docs
repo -
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.
-
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.
-
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
You can easily submit an edit suggestion. Note that you must have a GitHub account and good knowledge of Markdown syntax.
- Navigate to the Polygon Wiki page that you want to edit.
- Scroll down until the end of that page
- Click on the link: Edit this page. It will forward you to the same page (Markdown format) hosted on GitHub.
- On the related GitHub page, click the pencil icon (similar to ) near the upper right corner of the file
- Apply your edits by modifying the Markdown file
- After you finish, scroll down until the end of that page to create a pull request
- 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.
- 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.
- Write a brief description of the changes you have made. If possible, include screenshots and references.
- 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 Wiki maintainers will review your PR and either accept it or submit our review.
Acceptable PRs will be approved & merged into the master
branch.
- 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.
This command generates static content into the build
directory and can be served using any static content hosting
service:
yarn build
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
Deployments leverage GitHub caching to improve build times. Currently, 3 levels of caching are implemented:
.docusaurus
: caches the site structure. The build process will update this as neededbuild
: caches the static assets to avoid regenerating any pages that have not changednode_modules
: caches node_modules based on the hash ofyarn.lock
. Any changes to package dependencies will invalidate and rebuild this cache
Current cache config is defined in build.yml. Caches can be viewed or invalidated in the GitHub repo settings.