Use GitHub markdown alert extension for warning

[manzt]

I assume the intent of the warning code block was: https://github.com/orgs/community/discussions/16925

Also tried to clarify the text.

[ilan-gold]

The reason I landed on that was to make it look nice with our docs build hatch run docs:build and I wanted a nice middle ground between the two. We could maybe make some sort of sphinx extension to convert from this version to that but I think what we have is ok for now

vs.

[ilan-gold]

If you think people generally go for the readme rather than docs, maybe we should change it....I guess our docs are basically just the README anyway...

[flying-sheep]

We’ll probably remove the warning before publishing anyway right?

[ilan-gold]

We’ll probably remove the warning before publishing anyway right?

I think we should put it on PyPI in an experimental state so people can use it instead of installing from here, no?

[flying-sheep]

OK sure, we can simply start by only publishing pre-release versions.

But then we want to use syntax that PyPI can actually render properly.

Btw: reStructuredText has wonderful built-in admonitions for exactly that purpose wink

[ilan-gold]

@flying-sheep will investigate PyPI rendering as well, but it's the same issue where it can't render the Github syntax (so we think, but need to check).

[flying-sheep]

OK, so PyPI uses readme-renderer, which in turn uses cmark-gfm for markdown.

As far as that parser is concerned, the admonitions don’t exist. They are instead part of GitHub’s post-processing like converting #123 into a PR link and so on (source: github/cmark-gfm#350. See also: pypa/readme_renderer#318)

So to see how things look on PyPI, do this:

uv run --isolated --with=readme-renderer[md] python -m readme_renderer README.md

GitHub doesn’t seem to give a fuck about properly rendering rST, so switching to rST is not a panacea: github/markup#1682

---

This leaves us between a rock and a hard place: either it looks “bad” on GitHub or it looks bad on PyPI.

The docs rendering of this PR’s version might be possible, see executablebooks/MyST-Parser#845

To be honest, I like the current compromise more than

[ilan-gold]

To be honest, I like the current compromise more than

Then let's close for now, I think. But we've learned something!