Switch to note admonition in readme

[Gitznik]

• I have added a news fragment under changelog.d/ (if the patch affects the end users)

Summary of changes

The current syntax does not render correctly and is not in line with the rest of the docs. I could not find any more usages of the other syntax in the docs.

See #1215 for the source of this PR.

Test plan

Tested by running nox -s build_docs and checking site/index.html

# command(s) to exercise these changes

[dukecat0]

Seems like it only works on mkdocs, but not Github.

[Gitznik]

Seems like it only works on mkdocs, but not Github.

True. On github it's as broken as before. I won't have time to look into how to fix it for both before my vacation, so someone else please feel free to take this over.

[chrysle]

Seems like it only works on mkdocs, but not Github.

Is that a problem? I always thought that's what a website is for.

[henryiii]

Github does have a syntax for admonitions, and it doesn't match anything else. I wonder if it could be supported via a plugin, though?

• https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts
• https://github.com/orgs/community/discussions/16925

[henryiii]

And I'm pretty sure the reason it's currently broken is due to the square bracket part being on the same line. If you added an extra empty line (which IIRC is allowed), then formatters will keep it as is instead of squishing them together.

But that doesn't solve showing this in the docs. So far I've just used conditional blocks to get both, but something more elegant would be nice.

[henryiii]

Ahh, found it in the third-party extensions page for Python-Markdown: https://github.com/dahlia/markdown-gfm-admonition

(From https://github.com/Python-Markdown/markdown/wiki/Third-Party-Extensions#additional-tags)

[henryiii]

[dukecat0]

@henryiii Thanks a lot for fixing this!

[Gitznik]

Great find @henryiii , thanks for taking this over 👌