myst_parser无法识别{code-cell}指令的问题求助

问题原因 #

myst_parser 默认仅支持基础的MyST语法指令（比如{admonition}），{code-cell} 这类Jupyter代码单元格指令需要依赖 myst-nb 扩展提供支持，它专门用于在Sphinx中处理Jupyter笔记本相关的MyST语法。

解决步骤 #

• 安装myst-nb扩展
  在你的PyPI环境中执行安装命令：

  pip install myst-nb
  

• 修改conf.py配置
  在docs/conf.py的extensions列表中添加myst_nb（注意使用下划线）：

  extensions = ["myst_parser", "myst_nb"]
  

• 验证配置
  重新构建Sphinx文档：

  sphinx-build -b html docs docs/_build/html
  

  此时{code-cell}指令会被正常识别，不会再抛出Unknown directive type警告。

额外说明 #

• 仅需安装myst-nb即可让Sphinx识别{code-cell}指令，无需额外安装ipykernel或jupyter-server（除非你需要实际运行代码单元格）。
• 无需在index.md中添加jupytext或kernelspec头信息，除非你需要将文档作为可执行笔记本使用。

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