README.md support for tabs, titled/collapsible callouts, numbered references, etc. with MyST (Markedly Structured Text) markdown
#213724
Replies: 2 comments
|
💬 Your Product Feedback Has Been Submitted 🎉 Thank you for taking the time to share your insights with us! Your feedback is invaluable as we build a better GitHub experience for all our users. Here's what you can expect moving forward ⏩
Where to look to see what's shipping 👀
What you can do in the meantime 💻
As a member of the GitHub community, your participation is essential. While we can't promise that every suggestion will be implemented, we want to emphasize that your feedback is instrumental in guiding our decisions and priorities. Thank you once again for your contribution to making GitHub even better! We're grateful for your ongoing support and collaboration in shaping the future of our platform. ⭐ |
|
Some of this exists in a limited form today, which may help while a feature like this is considered:
Tabs and numbered figure references aren't supported. A request like this is best made in this feedback category, as you did, and upvoted by others. Since it's about rendering opt-in MyST, it may also help to include a short list of the specific features that would matter most, because narrower requests are easier to evaluate. |
Uh oh!
There was an error while loading. Please reload this page.
🏷️ Discussion Type
Product Feedback
💬 Feature/Topic Area
Code Search and Navigation
Body
MyST (Markedly Structured Text) is the standardized Markdown at feature-parity with Asciidoc & reStructuredText
Right now a
README.mdis usually a hand-copied, simplified duplicate of a project's real documentation. The install commands exist in three places. The architecture diagram exists in two. The example code is a paste of a file that changed four releases ago. Everything you'd want to fix that — tabs, captions, "see Figure 2", including a real source file — has been requested here for years, separately, and mostly closed by a stale bot rather than by a decision.MyST Markdown already does all of it. It's a documented superset of CommonMark, it's what Jupyter Book 2 and a large amount of scientific and technical documentation are written in, and it renders on GitHub today as ordinary Markdown — just with the structure stripped out.
This is a request to render it properly, opt-in, so a project can keep one copy of its docs instead of two.
People have been asking for these pieces for a decade
Different people, different years, same underlying gap. None of them are asking for a new Markdown flavour — they're asking for structure that documentation has everywhere except here.
What it would look like
Tabs, so one
README.mdserves every readerPick your package manager, OS, or language once and every example on the page follows. Today the options are three stacked code blocks, a wall of
<details>, or a separate README per language.Syntax: tabs
Callouts with your own title, nested, and collapsible
Alerts were a great addition, but the five titles are fixed and they can't be nested or collapsed. The alerts thread itself has people asking for custom titles (for translation, among other reasons) and for alerts inside collapsible sections.
Syntax: admonitions
Include the actual file, so examples can't go stale
Pull a real source file, a line range, or the section between two markers straight into the README. Also include your CHANGELOG or a shared install snippet once and reuse it across every package README in a monorepo.
Syntax: include and embed
Captions and references that renumber themselves
Give a figure a caption and a label, then write "see Figure 2" and have it stay correct when you add a figure above it. Same for tables and sections. Renaming a heading no longer breaks every link to it.
Syntax: figures · cross-references
Numbered equations
Math already renders here. What's missing is numbering and being able to refer to an equation from the text — the thing #151728 asked for so the same file could go to Pandoc untouched.
Syntax: math and equations
Code blocks with a filename and highlighted lines
Show which file a snippet belongs to and draw the eye to the two lines that matter, instead of putting
// config.tsin a comment and hoping.Syntax: code directive
Small things that add up
Keyboard keys, abbreviations with expansions on hover (useful for screen readers too), definition lists, and tables whose cells can hold lists or code.
Syntax: typography · tables
Why MyST rather than inventing new syntax
> [!NOTE]alerts and turns them into admonitions, and its docs recommend syntax specifically because it degrades cleanly on GitHub. The ecosystem is meeting GitHub halfway; this completes the loop.To be clear about what already works: footnotes, tables, task lists, alerts, math, Mermaid, and collapsible sections all render fine today. This isn't about those.
What this is not asking for
No code execution. No
iframes, plugins, or injected HTML. No fetching remote content while rendering. Includes stay inside the repository — the same trust boundary as an image path today. The old blanket objection to includes was the overhead of auditing every markup format for security holes; this is one documented format with a published test suite, not an open-ended extension point.If this would help you, please add your voice
<details>workaround. Real examples are the strongest argument here.Alerts shipped off the back of #16925. That's the precedent — a community thread with enough concrete demand behind it.
All reactions