MyST Markdown Basics¶
🌐 AI ReaderRead this document in English or ask questions: Open in Claude, ChatGPT, or Gemini ↗
This document shows what MyST Markdown can do in Sphinx. The “On this page” navigation on the right lists the H2 and H3 headings of this page; H4 and deeper stay out of it.
Cross-File Links¶
Link to a whole document¶
Link by doc_id; the link text is the target document’s title:
Level 3 (a document three folders deep)
custom link text (a reStructuredText document)
Jupyter Notebook (a Jupyter Notebook)
Link to a section¶
Put a label (<doc_id>-<slug>)= on the line above the heading; the doc_id prefix keeps it unique across the site. For example Admonition points to a section below, and The Linked Section to a section of another document.
Link inside the page¶
myst_heading_anchors = 3 gives H1 to H3 GitHub style anchors, so a plain Markdown link like jump to Admonition works in the page, and on GitHub too.
Note
This only works for ASCII headings. A CJK heading gets no usable HTML anchor: use the (<doc_id>-<slug>)= label and {ref} instead.
Admonition¶
Note
A note, written as a backtick fence. GitHub shows it as a code block.
Tip
A tip, written as a colon fence; the Markdown inside renders as usual.
Warning
A warning.
Code Blocks¶
import secrets
import string
print("".join(secrets.choice(string.ascii_letters) for _ in range(12)))
python3 .claude/skills/sphinx-myst-kb-site/scripts/new_doc_id.py
Tables and Lists¶
Format |
File name |
Where the metadata lives |
|---|---|---|
MyST Markdown |
|
YAML front matter |
reStructuredText |
|
the field list at the top of the file |
Jupyter Notebook |
|
the notebook |
A task list (tasklist extension)
An open task
- Term
A definition list (deflist extension).
Inline HTML¶
Click to expand
Inline HTML is passed through as is; Markdown inside still renders.