MyST Markdown Basics

🌐 AI Reader Read 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

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

README.md

YAML front matter

reStructuredText

README.rst

the field list at the top of the file

Jupyter Notebook

README.ipynb

the notebook metadata

  • 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.

Heading Levels

An H3 heading shows in the right side navigation

An H4 heading does not

Body text.

Math

\[E = mc^2\]