Docs Contributions

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!

When deciding where to contribute to Gatsby (docs or blog?), check out the docs templates page.

Top priorities

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 Pull Request to address one of these issues, you can remove the “help wanted” label. As well, examine the list of articles that haven’t been fully fleshed out at the Stub List.

Options for contributing to the Gatsby docs

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 www site 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.

Fixing image and link paths

If you find a broken image URL in the Gatsby docs, it should be fixed and kept relative to the site source rather than linked to the remote repo on GitHub. This ensures that when the site is deployed, all images are included in the build.

To address missing images, check the doc or tutorial source in the Gatsby repo to see if it was moved in its history and if the images are still in its old location. Check to see if those images are also referenced from more than one doc. If they aren’t, move them to the new directory location (and update URL references relative to the content, if necessary). If they are referenced in more than one location, use relative paths and don’t duplicate images.

If you find a broken link in the Gatsby docs, feel free to fix it and submit a PR!

Keep in mind that some links in here are already correct because they work on gatsbyjs.org. While it would be nice for links in documentation to work on GitHub, having them working on gatsbyjs.org is a higher priority!

Headings

Docs with frontmatter metadata at the top including a title will automatically receive an <h1> heading in the rendered page, and it should be the only one. Additional headings in docs content should start with <h2>, denoted by ## in Markdown.

For the purposes of an accessible document outline, content headings should go in order from h2-h4 (####) until all levels have been established. This will ensure the Gatsby docs have a content hierarchy that works well for users of assistive technology. Read more about the importance of headings and semantic structure in HTML.

Modifying Markdown files

💡 New to writing Markdown? Check out the Gatsby guide on Markdown Syntax!

1. 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.
2. 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.

3. 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!

Converting a document from a stub

If you wrote a new document that was previously a stub, there are two things you need to update.

1. Remove the frontmatter that links to the issue

2. Edit www/src/data/sidebars/doc-links.yaml by removing the asterisk behind the document’s title:

3. (Optional) if the name of the title seems long, consider adding a breadcrumbTitle to the entry in the doc-links.yaml file that is a shorter version of the title, and will show up in the breadcrumb on the docs page instead.

Docs site setup instructions

After going through the development setup instructions, 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 and docs directories. There are also some examples in the repo that are referenced in docs.

• Fork and clone the Gatsby repo.
• For docs-only changes, consider using git checkout -b docs/some-change or 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: cd www
• Install dependencies with Yarn: yarn install
• Add the following env variable to an .env.development file inside the www directory to enable image placeholders: GATSBY_SCREENSHOT_PLACEHOLDER=true. This will speed up building the docs site significantly!
• Start a build of www with gatsby develop.
• Edit Markdown files in the docs and contributing folders, as well as the YAML sidebar files.
• View the changes in your browser at http://localhost:8000.
• Commit your changes and submit a pull request!

Docs renaming instructions

Sometimes it makes sense to move or rename a file as part of docs restructuring or for content clarification. While we recommend keeping URLs consistent as often as possible, here are some tips to minimize errors and keep the docs in a good state:

• Run proposed structure changes by the Gatsby docs team in a GitHub issue to ensure your change is accepted.
• Update all instances of the old URL to your new one. Find and replace in VS Code can help. Check that the context of the original link reference still makes sense with the new one.
• For SEO purposes, add a redirect to the createPages function in www/gatsby-node.js. Here’s an example:

Claim your swag

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!

Want more?

Check out our additional pages on docs contributions:

• Gatsby Style Guide
• Docs Templates
• How to Write a Stub