There are a lot of ways we can improve docs tooling to make the docs team more efficient and make our docs better.
Manifest parser
We need a new docs manifest parser/generator! Here's what I'd like to see:
It should use toc.json as the source of truth, with manifest.json being built as a totally separate/machine-generated artefact.In turn, that means that manifest.json should pull page titles from the markdown, rather than needing to set it in multiple placesIt should be possible to generate documentation (e.g. the data docs) separately from generating the manifest, and this should mean we don't need to generate an intermediate root-manifest.json anymoretoc.json should be extended to provide a wildcard option, so auto-generated docs don't need to be explicitly listed inside the file, and can be included in the correct place inside the handbook outline
Linting
I'd also like to propose the addition of a markdown linter. This is partly to aid the parser, for example to ensure that all docs have an h1 title, but also to improve the consistency of our markdown formatting (consistent heading syntax, line breaks, wrapping, etc.). Right now it varies pretty wildly and having a consistent format would be super valuable.
markdownlint and remark-link seem like the leading candidates. Does anyone have an opinion or experience on either of these?
To be clear I don't want to lint grammar/spelling, just the markdown syntax.
There are a lot of ways we can improve docs tooling to make the docs team more efficient and make our docs better.
Manifest parser
We need a new docs manifest parser/generator! Here's what I'd like to see:
It should usetoc.jsonas the source of truth, withmanifest.jsonbeing built as a totally separate/machine-generated artefact.In turn, that means thatmanifest.jsonshould pull page titles from the markdown, rather than needing to set it in multiple placesIt should be possible to generate documentation (e.g. the data docs) separately from generating the manifest, and this should mean we don't need to generate an intermediateroot-manifest.jsonanymoretoc.jsonshould be extended to provide a wildcard option, so auto-generated docs don't need to be explicitly listed inside the file, and can be included in the correct place inside the handbook outlineLinting
I'd also like to propose the addition of a markdown linter. This is partly to aid the parser, for example to ensure that all docs have an h1 title, but also to improve the consistency of our markdown formatting (consistent heading syntax, line breaks, wrapping, etc.). Right now it varies pretty wildly and having a consistent format would be super valuable.
markdownlint and remark-link seem like the leading candidates. Does anyone have an opinion or experience on either of these?
To be clear I don't want to lint grammar/spelling, just the markdown syntax.