test: enforce valid JSON in fenced markdown code blocks

[nejch]

Changes:

Enforces valid JSON for fenced code blocks in docs so that static site generators can auto-generate tabbed json/yaml examples.

I tried to also add some helpful annotations for CI, hopefully works as expected but could be tried on a dummy PR without the fixes in f0d2bd5 applied.

Example run before the fix (not sure if too noisy and only errors should be reported):

~/repos/renovate$ yarn doc-fence-check
yarn run v1.22.15
$ node tools/check-fenced-code.mjs
Linting docs/development/adding-a-package-manager.md..
Linting docs/development/branches-commits.md..
Linting docs/development/bump-node-major.md..
Linting docs/development/configuration.md..
Invalid JSON in fenced code block (docs/development/configuration.md lines 55-63): Unexpected token : in JSON at position 10
Linting docs/development/design-decisions.md..
Linting docs/development/issue-labeling.md..
Linting docs/development/local-development.md..
Linting docs/development/minimal-reproductions.md..
Linting docs/development/new-package-manager-template.md..
Linting docs/development/readme.md..
Linting docs/development/shareable-configs.md..
Linting docs/development/triage-guide.md..
Linting docs/usage/bazel.md..
Linting docs/usage/config-presets.md..
Invalid JSON in fenced code block (docs/usage/config-presets.md lines 98-113): Unexpected token : in JSON at position 12
Invalid JSON in fenced code block (docs/usage/config-presets.md lines 116-122): Unexpected token : in JSON at position 11
Invalid JSON in fenced code block (docs/usage/config-presets.md lines 140-143): Unexpected token : in JSON at position 11
Invalid JSON in fenced code block (docs/usage/config-presets.md lines 226-238): Unexpected token . in JSON at position 64
Invalid JSON in fenced code block (docs/usage/config-presets.md lines 241-244): Unexpected token : in JSON at position 11
Invalid JSON in fenced code block (docs/usage/config-presets.md lines 249-252): Unexpected token : in JSON at position 11
Linting docs/usage/configuration-options.md..
Linting docs/usage/configuration-templates.md..
Linting docs/usage/dependency-pinning.md..
Linting docs/usage/docker.md..
Invalid JSON in fenced code block (docs/usage/docker.md lines 128-135): Unexpected token : in JSON at position 18
Linting docs/usage/examples/self-hosting.md..
Linting docs/usage/faq.md..
Invalid JSON in fenced code block (docs/usage/faq.md lines 182-190): Unexpected token : in JSON at position 14
Invalid JSON in fenced code block (docs/usage/faq.md lines 195-203): Unexpected token : in JSON at position 14
Invalid JSON in fenced code block (docs/usage/faq.md lines 208-216): Unexpected token : in JSON at position 14
Linting docs/usage/getting-started/installing-onboarding.md..
Linting docs/usage/getting-started/private-packages.md..
Linting docs/usage/getting-started/running.md..
Linting docs/usage/getting-started/use-cases.md..
Linting docs/usage/gitlab-bot-security.md..
Linting docs/usage/golang.md..
Invalid JSON in fenced code block (docs/usage/golang.md lines 48-53): Unexpected token : in JSON at position 15
Linting docs/usage/java.md..
Linting docs/usage/javascript.md..
Linting docs/usage/key-concepts/automerge.md..
Linting docs/usage/key-concepts/dashboard.md..
Linting docs/usage/key-concepts/scheduling.md..
Linting docs/usage/known-limitations.md..
Linting docs/usage/modules/datasource.md..
Linting docs/usage/modules/manager.md..
Linting docs/usage/modules/platform.md..
Linting docs/usage/modules/versioning.md..
Linting docs/usage/node.md..
Linting docs/usage/noise-reduction.md..
Invalid JSON in fenced code block (docs/usage/noise-reduction.md lines 30-38): Unexpected token : in JSON at position 16
Invalid JSON in fenced code block (docs/usage/noise-reduction.md lines 81-90): Unexpected token : in JSON at position 16
Invalid JSON in fenced code block (docs/usage/noise-reduction.md lines 93-102): Unexpected token : in JSON at position 16
Invalid JSON in fenced code block (docs/usage/noise-reduction.md lines 151-162): Unexpected token : in JSON at position 16
Linting docs/usage/nuget.md..
Invalid JSON in fenced code block (docs/usage/nuget.md lines 32-41): Unexpected token : in JSON at position 7
Invalid JSON in fenced code block (docs/usage/nuget.md lines 52-59): Unexpected token : in JSON at position 7
Invalid JSON in fenced code block (docs/usage/nuget.md lines 64-74): Unexpected token : in JSON at position 11
Linting docs/usage/php.md..
Linting docs/usage/python.md..
Invalid JSON in fenced code block (docs/usage/python.md lines 34-39): Unexpected token : in JSON at position 20
Invalid JSON in fenced code block (docs/usage/python.md lines 65-70): Unexpected token : in JSON at position 10
Invalid JSON in fenced code block (docs/usage/python.md lines 78-83): Unexpected token : in JSON at position 10
Invalid JSON in fenced code block (docs/usage/python.md lines 87-90): Unexpected token : in JSON at position 19
Linting docs/usage/ruby.md..
Linting docs/usage/rust.md..
Linting docs/usage/self-hosted-configuration.md..
Linting docs/usage/self-hosted-experimental.md..
Linting docs/usage/semantic-commits.md..
Linting docs/usage/setup-azure-devops.md..
Linting docs/usage/templates.md..
Linting docs/usage/troubleshooting.md..
Linting docs/usage/updating-rebasing.md..
23 issues found.
error Command failed with exit code 1.

Context:

This is another tiny step towards #7031, to make things like renovatebot/renovatebot.github.io#65 automatically generate YAML blocks after the feature itself is implemented. As suggested in #7031 (comment).

Documentation (please check one with an [x])

• I have updated the documentation, or
• No documentation update is required

How I've tested my work (please tick one)

I have verified these changes via:

• Code inspection only, or
• Newly added/modified unit tests, or
• No unit tests but ran on a real repository, or
• Both unit tests + ran on a real repository

[HonkingGoose]

I like this idea, but have some suggestions to improve the end-user experience. 😉

[rarkins]

This is great, although for some reason I'd thought that prettier would check these for us and complain if json blocks weren't valid JSON.

[HonkingGoose]

This is great, although for some reason I'd thought that prettier would check these for us and complain if json blocks weren't valid JSON.

I would have expected that too... 😄

I think Prettier doesn't format these JSON fences properly - or doesn't complain about it - because it's not valid JSON. At least, if I'm reading this explanation from a member of the Prettier org correctly: ¹

Prettier intentionally formats code blocks (where a supported language is specified). I think that's a really cool feature!

In your case – that's not really vue code in your code block, is it? It looks like part of a JS snippet. By marking the block with "vue", Prettier treats it like a .vue file. If you'd stick that code in a .vue file, it would be treated as text, wouldn't it? So Prettier normalizes all the weird spaces and line breaks into a more conventional sentence – where there's just one space between every "word".

Now, what would happen if you tagged it with js? Nothing, in this case. The code isn't valid JS, so Prettier would ignore it. Here are some things I recommend when it comes to code blocks in markdown:

• Use syntactically valid code if you tag the block with a language.
• Don't tag with a language otherwise.
• Use a <!-- prettier-ignore --> comment before if needed.

Footnotes

1. https://github.com/prettier/prettier/issues/5971#issuecomment-472737500 ↩

[renovate-release]

🎉 This PR is included in version 29.4.3 🎉

The release is available on:

• GitHub release
• 29.4.3

Your semantic-release bot 📦🚀