MyST Markdown 基础¶

这篇文档演示 MyST Markdown 在 Sphinx 里能做的事情。右侧的 "On this page" 导航列出本页的 H2 和 H3 标题, H4 及更深的标题不进导航。

跨文件引用¶

用 doc_id 引用, 链接文字自动取目标文档的标题:

小节锚点的写法是在标题上一行写 (<doc_id>-<slug>)=, 带上 doc_id 前缀保证全站唯一。例如 Admonition 指向本页下面的小节, 被引用的小节指向另一篇文档里的小节。

myst_heading_anchors = 3 让 H1 到 H3 自动有 GitHub 风格的锚点, 所以跳到 Admonition 这种普通 Markdown 链接在页内也能用, GitHub 上也能用。

备注

这种写法只适合英文标题。中文标题生成不了 HTML 锚点, 中文标题请用上面的 (<doc_id>-<slug>)= 加 {ref} 的写法。

备注

这是一个 note。用 backtick fence 写, 在 GitHub 上会显示成代码块。

小技巧

这是一个 tip。用 colon fence 写, 里面的 Markdown 照常渲染。

警告

这是一个 warning。

from sanhe_me_kb.doc_id import new_doc_id

print(new_doc_id())

mise run new-doc-id

点击展开

内嵌的 HTML 原样输出, 里面的 Markdown 也照常渲染。

正文。

\[ E = mc^2 \]