renovatebot/renovatebot.github.io

Use admonitions instead of bolded text

Closed this issue · 4 comments

HonkingGoose commented

What would you like to be able to do?

Our documentation Markdown highlights important things like this:

**Note:** thing to note.
**Warning:** thing to warn about.

The bolded parts stand out, but I think we can do better.
I'd like us to use admonition blocks. 1

To make an admonition in the Markdown you use !!! then the type 2 of admonition, and you use 4 spaces to indent the body text of the admonition. 3 Like this:

Shareable config presets can only be used with the JSON format, other formats are not supported.

!!! warning
    `default.json` is intended for use with presets only!

!!! warning
    Do not use a `renovate.json` file as a preset.

!!! info
    We've deprecated the use of a `renovate.json` file for presets as this can cause issues if the repository configuration uses a `renovate.json` file as well.

Did you already have any implementation ideas?

Yup, already made a proof of concept: https://github.com/HonkingGoose/renovatebot.github.io/tree/admonition-poc

You'll need to edit the docs/config-presets.md file after installing the dependencies, and then run mkdocs serve to preview the changes.

Screenshot:

Side by side comparison, left uses the default Material for MkDocs admonitions, the right is our current published site.

side-by-side-admonition-comparison

Footnotes

  1. https://squidfunk.github.io/mkdocs-material/reference/admonitions/ ↩

  2. https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types ↩

  3. https://squidfunk.github.io/mkdocs-material/reference/admonitions/#usage ↩

rarkins commented

I like it, although let's not overuse it :)

HonkingGoose commented

I agree, we should not overuse admonitions, as that will be too much visual noise.

Which process do you prefer @rarkins?

  • One big PR to find and replace all admonitions, and rewrite the text to drop unncessary admonitions.
  • Two separate PRs:
    • Find/replace all current admonitions as-is.
    • Rewrite text to drop admonitions.
viceice commented

I think it depends on the amount 🙃 maybe we should do it im multiple pr's, but not too small

HonkingGoose commented

I'll start with the PR to enable the feature on the docs publishing repo first, as we need that for the admonitions to render properly. 😉

  • 👍1