Re: [csswg-drafts] Build markdown documents to HTML in the CI workflow (#13432)

@frivoal Short answer: I think what’s set up here now — using Python-Markdown — is the best choice and does everything y’all need, as far as supporting all markdown features in the sources here. So that’s what I’d recommend.


Longer answer:

> I wonder if we have a dependency on any particular flavor of markdown.

I think there are some markdown tables in some of the sources, and we need to fenced-code syntax-highlighting stuff. So for those, we need GitHub-flavored-markdown support. But the good news is: Python-Markdown supports those. See the bit of the change at https://github.com/w3c/csswg-drafts/pull/13432/files#diff-eeeae3642da5cedb2d38612b2e6193054b2171632b614a104842144be1b5f74eR31:

> ```python
>     md = markdown.Markdown(extensions=["fenced_code", "tables"])
> ```


> I don't know what the current server uses, but it'd be good to check if that's the same as what's proposed here or not. Another consideration is that quite a few of our markdown files start their life as documents served by GitHub, and might be using various features of GitHub flavored markdown (which may or may not be preserved by the current server). If so, and if we want to support that, maybe using a tool like [joeyespo/grip](https://github.com/joeyespo/grip?rgh-link-date=2026-02-03T13%3A52%3A40Z) could help.

I think the only other tool to possibly consider is `cmark-gfm` https://github.com/github/cmark-gfm. It’s a C program (though it has Python bindings we could use). I don’t know what the install story for it is — as far as us being able to add a cross-platform install step, to enable contributors to run it locally if they wanted to. I do know that there is a brew package for it. But regardless, if we were to use that, I think we’d need to have the docs explain how to install it.

For Python-Markdown in contrast, we don’t need to do that.

But anyway, as far as I can see, the only additional GFM feature that switching to `cmark-gfm` would buy us is: You could use the special `> [!NOTE]` etc GFM admonitions stuff, and get the pretty HTML rendering for that in the HTML output. Python-Markdown doesn’t (yet) support converting that to the same pretty rendering.

But none of the existing markdown sources here are using those admonitions. Yet. So there’d be no reason in choosing  `cmark-gfm` for that at this point — I mean, just to get support for a GFM feature that none of sources are using.

That said, it would not be a big deal at all at some point later to update the build here to switch over to using `cmark-gfm`. I would be happy to set up, if at some point later y’ll decide you want to use those GFM admonitions.

Otherwise, all that said, as far as I can see, the choice really is just between Python-Markdown and `cmark-gfm`. There are no other alternatives that need to be considered.

-- 
GitHub Notification of comment by sideshowbarker
Please view or discuss this issue at https://github.com/w3c/csswg-drafts/pull/13432#issuecomment-3844299923 using your GitHub account


-- 
Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config

Received on Tuesday, 3 February 2026 23:10:28 UTC