Gatsby, unsurprisingly, uses Gatsby for its documentation website. Thank you in advance and cheers for contributing to Gatsby documentation! As of February 2019, over 800 people have contributed. It’s people like you that make this community great!
On this page:
- Top priorities
- Options for contributing to the Gatsby docs
- Docs site setup instructions
- Claim your swag
- Want more?
Check the GitHub repo for issues labeled with “documentation” and “good first issue” for your first time contributing to Gatsby, or “documentation” and “help wanted” to see all documentation issues that are ready for community help. Once you start a PR to address one of these issues, you can remove the “help wanted” label.
When working on the Gatsby.js documentation, you can choose between two major styles of working:
- Work directly in the GitHub UI, using the “Edit this File” and commit capabilities without having to clone the repository. This is useful for quick documentation updates, typo fixes, and lightweight Markdown changes.
- Clone the Gatsby.js repo and get the
wwwsite up and running locally. This is necessary for more thorough documentation content and infrastructure changes. Learn how to get set up in the Gatsby docs setup instructions.
- If you want to add/modify any Gatsby documentation, go to the docs folder or contributing folder on GitHub and use the file editor to edit and then preview your changes.
Before committing the change and raising a PR in the UI, you need to make sure the PR meets the docs contribution criteria:
- Follow the standards outlined in the Gatsby Style Guide.
If your PR did not come from an issue written by the core team, please add a comment to your PR that explains why it should be included in the docs, according to the Docs Decision Tree.
Note: If your issue and/or PR doesn’t meet the above contribution criteria, it may receive a comment reminding you to do so. If, after two weeks, these updates haven’t been made, your issue and/or PR may be closed, which helps us triage issues and PRs efficiently. You can request that it be reopened if and when you are ready to make the updates required.
- GitHub then allows you to commit the change and raise a PR right in the UI. This is the easiest way you can contribute to the project!
If you wrote a new document that was previously a stub, there are two things you need to update.
- Remove the frontmatter that links to the issue
... title: Example Document - - issue: https://github.com/gatsbyjs/gatsby/issues/00000 + - ...
www/src/data/sidebars/doc-links.yamlby removing the asterisk behind the document’s title:
... - - title: Example Document* + - title: Example Document link: /docs/example-document/ ...
After going through the development setup instructions above, there are a few additional things that are helpful to know when setting up the Gatsby.js docs site. which mostly lives in the www directory.
- Clone the Gatsby repo as described above.
- For docs-only changes, consider using
git checkout -b docs/some-changeor
git checkout -b docs-some-change, as this will short circuit the CI process and only run linting tasks.
- Change directories into the docs site folder:
- Install dependencies with Yarn:
- Add the following env variable to an
.env.developmentfile to enable image placeholders:
GATSBY_SCREENSHOT_PLACEHOLDER=true. This will speed up building the docs site significantly!
- Start a build of
- Edit Markdown files in the docs and contributing folders, as well as the YAML sidebar files.
- View the changes in your browser at
- Commit your changes and submit a pull request!
After your first code contribution to the Gatsby repo (including documentation) you become eligible for a free shirt or pair of socks. See the swag page for more details!
Check out our additional pages on docs contributions:
Edit this page on GitHub