Edit on GitHub View source

MyST 扩展配置详解¶

当前配置解释¶

您当前在配置文件中启用了以下 MyST (Markedly Structured Text) 扩展:

dollarmath: 允许使用 $...$ 和 $$...$$ 语法插入内联和块级 LaTeX 数学公式。
amsmath: 支持 AMS 数学环境，如 \begin{align}...\end{align}。
deflist: 启用定义列表语法，格式为:
```
术语
: 定义
```
html_admonition: 允许在 Markdown 中使用 HTML 格式的提示框。
html_image: 支持直接使用 HTML <img> 标签及其属性。
colon_fence: 允许使用 ::: 代替传统的 ``` 作为代码块分隔符。
smartquotes: 自动将直引号 ("...") 转换为弯引号 ("...")。
replacements: 自动替换常见表达式，例如将 (c) 替换为 ©。
linkify: 自动将URL文本转换为可点击链接。

推荐的其他 MyST 扩展¶

除了您已经使用的扩展外，以下是一些可能对文档有用的其他 MyST 扩展:

tasklist: 启用任务列表语法 (- [ ] 和 - [x])，适合表示待办事项。
```
- [x] 已完成任务
- [ ] 待办任务
```
fieldlist: 支持字段列表语法，格式为:
```
:字段名: 字段内容
```
footnotes: 增强脚注支持，可使用 [^label] 语法创建脚注。
strikethrough: 启用删除线语法，使用 ~~文本~~ 表示。
attrs_inline: 允许为内联元素添加属性，如 [文本]{.class #id attr=value}。
attrs_block: 可以为块元素添加属性，例如:
```
{.class #id attr=value}
# 标题
```
substitution: 支持变量替换功能，使用 {{变量}} 语法。
sub_sup: 支持上标 ^上标^ 和下标 ~下标~ 语法。

完整推荐配置¶

以下是一个包含所有有用扩展的完整配置:

myst_enable_extensions = [
    # 您已有的扩展
    "dollarmath",
    "amsmath", 
    "deflist",
    "html_admonition",
    "html_image",
    "colon_fence",
    "smartquotes",
    "replacements",
    "linkify",
  
    # 推荐添加的扩展
    "tasklist",
    "fieldlist",
    "footnotes",
    "strikethrough",
    "attrs_inline",
    "attrs_block",
    "substitution",
    "sub_sup",
]

其他有用的 MyST 配置选项¶

除了扩展外，您还可以考虑以下配置选项:

# 自定义替换规则
myst_substitutions = {
    "项目名称": "我的项目",
    "版本号": "1.0.0",
}

# 定义要识别的URL协议
myst_url_schemes = ["http", "https", "mailto", "ftp", "git"]

# 启用直接解析 HTML
myst_enable_extensions = ["html_image", "html_admonition"]

# 配置自动生成标题引用
myst_heading_anchors = 3  # 为 h1-h3 级别标题生成锚点

# 扩展代码围栏语言
myst_fence_as_directive = ["mermaid", "plotly"]

注意事项¶

不要启用过多不必要的扩展，以避免潜在的语法冲突。
某些扩展（如 substitution）可能需要额外的配置才能完全发挥作用。
如果您正在与多人协作编写文档，确保团队了解这些扩展语法。
考虑您的部署环境是否支持所有这些扩展。
对于数学公式密集的文档，考虑设置 myst_update_mathjax = False 以提高性能。

根据您文档的具体需求，您可以选择性地添加这些推荐扩展和配置选项。