Sphinx中admonitions无法渲染为样式框的问题排查

• MyST扩展配置不全：在conf.py里需要明确启用admonition和colon_fence扩展，添加以下配置：

  myst_enable_extensions = [
      "admonition",
      "colon_fence",
  ]
  

  colon_fence是支持:::这种围栏语法的核心，缺了它会把admonition代码当成纯文本。

• myst_parser版本过低：旧版本的myst_parser可能不支持这种新式admonition语法，执行命令更新到最新版：

  pip install --upgrade myst_parser
  

• 文档文件格式错误：确保你的文档是.md后缀，myst_parser只处理Markdown文件，.rst文件需要用reStructuredText的admonition语法（比如.. seealso::）。

• 扩展加载有误：检查conf.py的extensions列表里是否正确包含'myst_parser'，注意拼写不要出错，比如不要写成myst_parsers。

• 构建缓存干扰：删除Sphinx的_build目录后重新执行构建命令，避免旧缓存导致的渲染异常。

内容的提问来源于stack exchange，提问作者atkat12