Repository navigation
RestructuredText: warning and note directives are not properly rendered #1682
Description
Activity
- changed the title
[-]RestructuredText directives warning and note directives are not properly rendered on github[/-][+]RestructuredText: warning and note directives are not properly rendered on github[/+]on Apr 11, 2023 - changed the title
[-]RestructuredText: warning and note directives are not properly rendered on github[/-][+]RestructuredText: warning and note directives are not properly rendered[/+]on Apr 11, 2023 Notes used to render with a little blue "info" icon, and warnings with a little yellow "warning" icon... but not anymore.
Maybe this broke it? https://github.blog/changelog/2023-12-14-new-markdown-extension-alerts-provide-distinctive-styling-for-significant-content/
This is markdown (that is designed for small blog entries),
we use/need RestructuredText (that is designed for technical documentation).Hold your horses, I’m with you haha. In this community discussion, they describe that they broke the rendering for the old markdown way of doing admonitions.
What I’m implying (but could have been clear about) is that maybe they still make rST render to whatever intermediate representation the old Markdown syntax rendered to and that way broke it?
Or maybe they never supported it, I don’t remember. Since they do support admonition rendering in Markdown, they should make rST and Asciidoc admonitions render the same way.
Reacted by Bernd SchatzDon't know what they do, the docutils works fine, so i assume they have some own stuff: post/pre-processor
before / after using the docutils !?
Or do they implement a complete own ResT parser !?PS: Regarding automated testing, there are probably still a few areas for improvement for ResT (and markdown):
Stale issue message
Not-a-stale-issue response
@humans please pin and make the bot go away thanks
Just for reference #68 was closed several years ago, because at the time it couldn't be implemented. I'm hoping that things have changed enough since then that'll be possible to provide the same experience to
ReSTthan it is available withGFM.Stale issue message
Still not stale. Please please add a label that shuts up the bot!
Reacted by Jason Meridth, Maxim Kim and Ryan DelaneyReacted by Nithin Philips@jmeridth could you please take a look here? Either #68 needs to be reopened or this needs to be triaged and labelled correctly.
The closing reason for #68 is no longer valid
@flying-sheep Taking a look. I've also added the
keeplabel to avoid being flagged by the stale bot. Thanks for the bump.Reacted by Philipp A., Agriya Khetarpal and Jimmy KromannRelated discussions, issues:
- Community
#86715: Possible regression: failed rendering of ReStructuredText files- why rST will likely not get support https://github.com/orgs/community/discussions/86715#discussioncomment-9706063:
"No one seems to mention that so far: is the root cause of all these due to GitHub switched from using sphinx to render rst to using pandoc to convert rst to md (or similar) and render from there?"
- potentially related, as @flying-sheep noted in this issue: https://github.blog/changelog/2023-12-14-new-markdown-extension-alerts-provide-distinctive-styling-for-significant-content/
- Community
- added a commit that references this issue
on Jan 15, 2026 When editing wiki pages, the GitHub user interface has an
Edit mode:drop-down menu that includes thereStructuredTextoption; it's been years since this issue was opened, but that official edit mode remains partially broken?Thanks for the report, and thanks for the detailed examples.
After investigating, this repo's RST renderer (via docutils) does generate correct semantic HTML for admonitions — including proper
class="admonition note"andclass="admonition warning"attributes. The raw HTML output from this gem is correct.However, the issue is in step 2 of the rendering pipeline: GitHub's HTML sanitizer aggressively strips
classandidattributes. Check out this part of the README for a fuller picture:The HTML is sanitized, aggressively removing things that could harm you and your kin — such as
scripttags, inline-styles, andclassoridattributes.Without those class attributes, the admonitions render as plain unstyled
<div>elements. This is a downstream sanitization/styling issue that this repo can't address — the correct HTML is being generated, but it's stripped before display.For admonition styling support, GitHub's feedback discussions would be the right venue to request that the sanitizer preserve or re-add admonition classes.
Closing as out of scope for this repository.
@zkoppert already exists, can you please elevate that to an internal issue/task? https://github.com/orgs/community/discussions/45829
Reacted by Ryan DelaneyReacted by megapatato
text of warning / note directives should be rendered in a box or/and in another color.
Currently it looks like this:
but it should look somehow like here -->
see also -->
https://sublime-and-sphinx-guide.readthedocs.io/en/latest/notes_warnings.html
IMHO this would be a big improvement for the readability of technical documentation with less effort for you for the implementation.