Skip to main content

Contribute to docs

Blockly's documentation lives in the same repository as Blockly's core code and first-party plugins.

Here is a quick overview of the facts you need to know to make a contribution to Blockly's documentation. These may be familiar to you if you have already made a contribution to core.

  • The working branch is main and all PRs should be made against main.
  • You must fill out the pull request template with the requested information.
  • Code snippets must conform to Blockly's style guide.
  • Use conventional commits in your commit messages and pull request titles.
  • PR summaries and comments should be human written, and AI usage is not allowed on issues labeled good first issue. Consult the AI policy for more information.
  • Docs are written in MDX.

Make and verify a documentation change​

  1. Run npm install at the top level of the repository to install dependencies.
  2. Make your changes. Documents can be found in the packages/docs/docs/ folder.
  3. Proofread your writing.
  4. Test any code snippets to ensure that the behavior works as described.
  5. Run npm run start from the packages/docs/ folder to run the docs site and view your changes locally. This can help you catch any typos, errors, or clunky wording.
  6. Run npm run lint and npm run format from the top level of the repository.
  7. If everything looks good, you are ready to open a PR against main with your changes. Docs changes undergo the same PR submission and review process as code changes.

Writing style​

Blockly docs should follow general best practices for technical writing. For an intro to technical writing, you can check out Google's Technical Writing One.

Best practices also include:

  • Link other relevant docs where possible, including guides, codelabs, and reference docs.
  • Use code snippets when explaining technical concepts.
  • If you're writing a new document, create an outline before writing to ensure that the document is well structured and includes all necessary information.

In general, you can look to the existing docs for examples of how Blockly docs are written.

Create a new document​

Occasionally, you may need to add a new document rather than editing an existing one. Find the appropriate folder in packages/docs/docs for your document and create the .mdx file.

Be sure to include front matter with the description, title, and Blockly banner image. For example, here's the front matter for this document:

---
description: Steps and guidelines for adding to Blockly's documentation.
title: Contributing to docs
image: images/blockly_banner.png
---

Once you have created the document, add an entry to sidebars.js. This will make your new document findable in the left sidebar. You can also add categories in sidebars.js.

For example, here's the sidebars.js entry for this document:

{
type: 'doc',
label: 'Overview',
id: 'guides/contribute/docs/contribute_to_docs',
},

Add redirects​

You should add a redirect whenever you move or rename a document. Changing the name or path of a document changes the URL, so adding a redirect means that bookmarks or other saved links will still resolve to the correct document.

Edit packages/docs/static/_redirects to include a new redirect. The format is source destination status code.

For example, if you were to rename this document, the redirect might look like this:

/guides/contribute/docs/contribute_to_docs /guides/contribute/docs/new_doc_name/ 301

Refresh the API docs​

The API reference docs are automatically generated with TypeDoc based on the contents of blockly_api.json (core Blockly API) and plugins_api.json (plugins API). Each time Blockly is released, these two files are regenerated so that the reference docs always reflect the state of the current release.

If you would like to view local API changes in the reference docs:

  1. Run npm run reference-refresh (or npm run plugins-reference-refresh if your changes are on a plugin) in the packages/docs/ folder.
  2. Run npm run start in the packages/docs/ folder. The reference docs will include local changes.
warning

Take care to never commit blockly_api.json or plugins_api.json. These files are committed automatically during the release process, and never by anyone contributing to Blockly.

If you regenerate blockly_api.json with npm run reference-refresh, or if you regenerate plugins_api.json with npm run plugins-reference-refresh, you should discard the changes before committing. Or, you can run the following git command to restore both files:

git restore packages/docs/blockly_api.json packages/docs/plugins_api.json