Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adding instructions for adding sub-pages to packages documentation. #43750

Merged
merged 2 commits into from
Sep 1, 2022
Merged

Adding instructions for adding sub-pages to packages documentation. #43750

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e835a13
Adding instructions for adding sub-pages to packages documentation.
ryanwelcher Aug 31, 2022
367c3c2
Fix typo.
ryanwelcher Aug 31, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions docs/contributors/documentation/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,25 @@ To add a new document requires a working JavaScript development environment to b

If you forget to run, `npm run docs:build` your PR will fail the static analysis check, since the `manifest.json` file is an uncommitted local change that must be committed.

### Documenting Packages

Package documentation is generated automatically but the documentation tool by pulling the contents of the README.md file located in the root of the package. Sometimes however, it is preferable to split the contents of the README out into smaller, easier to read portions.
gziolo marked this conversation as resolved.
Show resolved Hide resolved

This can be accomplished by creating a `docs` directory in the package and adding `toc.json` file that contains references other markdown files also contained in the `docs` directory. The `toc.json` file should contain an array of pages to be added as sub-pages of the main README file. The formatting follows the [`manifest.json`](https://github.com/WordPress/gutenberg/blob/HEAD/docs/manifest.json) file that is generated automatically.

In order for these pages to be nested under the main package name, be sure to set the `parent` property correctly. See the example below that adds child pages to the [`@wordpress/create-block` section](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/).

```json
[
{
"title": "@wordpress/create-block External Template",
"slug": "packages-create-block-external-template",
"markdown_source": "../packages/create-block/docs/external-template.md",
"parent": "packages-create-block"
}
]
```

### Using links

It's likely at some point you'll want to link to other internal documentation pages. It's worth emphasizing all documents can be browsed in different contexts:
Expand Down