Run eslint with `--cache` to speed up pre-commit scripts.
This was added to the `pnpm run lint` script in
b7f9495a (build: add eslint --cache file, 2022-08-27)
and doesn't seem to be causing any issues.
I haven't enabled `--cache` for `prettier` since as of prettier 2.8.0,
their cache invalidation doesn't yet work with prettier plugins.
Cache eslint using `--cache-strategy content` instead of the default
`--cache-strategy metadata`.
By default, `eslint` uses the file metadata (e.g. modification time)
to detect when the cache should be invalidated.
However, this is not efficient with `git`, since git constantly changes
the modification time,
e.g. running `git switch main && git switch original-branch` would not
change the file contents, but would change the file mtimes and force
eslint to re-lint everything.
Using the file contents is slower (~3% for me), but more resilient.
See
https://eslint.org/docs/latest/use/command-line-interface#--cache-strategy
[Prettier 2.7.0](https://prettier.io/blog/2022/06/14/2.7.0.html) added
a `--cache` CLI option to greatly speed up subsequent prettier runs.
By default, the cache is stored in
`./node_modules/.cache/prettier/.prettier-cache` and uses an `md5`
checksum of the contents as the cache-key.
On my PC, running `pnpm run lint` used to take 13.9 seconds, but now
it only takes 6 seconds.
Potential issues
----------------
Although updating Node.JS/Prettier will invalidate the cache,
updating or changing prettier plugins won't invalidate the cache.
Since we do use `prettier-plugin-jsdoc` in Mermaid, this might cause
a minor issue, but CI should catch it.
YAML front-matter is currently only used for Vitepress.
Because of that, to avoid confusion, we can remove this YAML
front-matter when converting the Markdown in packages/mermaid/src/docs
to go into the `docs/` folder for GitHub browsing.
Add the auto-generated header after any YAML front-matter blocks.
YAML front-matter is normally only valid in Markdown when it's at the
beginning of the Markdown file. GitHub/Vitepress may otherwise render
it incorrectly.
Change the `transformBlocks` function, which transforms a markdown str,
and instead making it into a
`transformMarkdownAst` function, which transforms a Markdown AST.
This means we can use the remark/unifiedjs plugin infrastructure, see
https://unifiedjs.com/learn/guide/create-a-plugin/
Vitepress uses YAML frontmatter to configure Vitepress specific
settings, see https://vitepress.vuejs.org/config/frontmatter-configs
We just need to use `remark-frontmatter` to add support for it.
GitHub also renders the YAML front-matter nicely in a table
automatically, but maybe we should instead strip it, if it's only
used by Vitepress?
