# MyST 扩展配置详解

## 当前配置解释

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

1. **dollarmath**: 允许使用 `$...$` 和 `$$...$$` 语法插入内联和块级 LaTeX 数学公式。
2. **amsmath**: 支持 AMS 数学环境，如 `\begin{align}...\end{align}`。
3. **deflist**: 启用定义列表语法，格式为:

    ```
    术语
    : 定义
    ```

4. **html_admonition**: 允许在 Markdown 中使用 HTML 格式的提示框。
5. **html_image**: 支持直接使用 HTML `<img>` 标签及其属性。
6. **colon_fence**: 允许使用 `:::` 代替传统的 ` ``` ` 作为代码块分隔符。
7. **smartquotes**: 自动将直引号 (`"..."`) 转换为弯引号 (`"..."`)。
8. **replacements**: 自动替换常见表达式，例如将 `(c)` 替换为 ©。
9. **linkify**: 自动将URL文本转换为可点击链接。

## 推荐的其他 MyST 扩展

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

1. **tasklist**: 启用任务列表语法 (`- [ ]` 和 `- [x]`)，适合表示待办事项。

   ```
   - [x] 已完成任务
   - [ ] 待办任务
   ```

2. **fieldlist**: 支持字段列表语法，格式为:

   ```
   :字段名: 字段内容
   ```

3. **footnotes**: 增强脚注支持，可使用 `[^label]` 语法创建脚注。
4. **strikethrough**: 启用删除线语法，使用 `~~文本~~` 表示。
5. **attrs_inline**: 允许为内联元素添加属性，如 `[文本]{.class #id attr=value}`。
6. **attrs_block**: 可以为块元素添加属性，例如:

   ```markdown
   {.class #id attr=value}
   # 标题
   ```

7. **substitution**: 支持变量替换功能，使用 `{{变量}}` 语法。
8. **sub_sup**: 支持上标 `^上标^` 和下标 `~下标~` 语法。

## 完整推荐配置

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

```python
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 配置选项

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

```python
# 自定义替换规则
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"]
```

## 注意事项

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

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