Gutenberg: Improve docs tooling (manifest parser and linter)

[chrisvanpatten]

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:

1. ~It should use toc.json as the source of truth, with manifest.json being built as a totally separate/machine-generated artefact.~
2. ~In turn, that means that manifest.json should pull page titles from the markdown, rather than needing to set it in multiple places~
3. ~It 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 anymore~
4. toc.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_.

[chrisvanpatten]

A lot of this has been done. Right now the two missing pieces are wildcard placeholders inside toc.json, and markdown linting.

Pending any strong opinions I think markdownlint and remark-lint. Both seem powerful and reasonably well-maintained. Anyone see anything in either package that makes it the better choice?

[ajitbohra]

remark-lint looks good to me with all the plugins to generate toc, process links

[chrisvanpatten]

Remark definitely seems a little more pluggable and customisable. I might work on a POC over the weekend 👍

[gziolo]

Nice, that would be awesome to have it included in the workflow. Lint all the things :)