如何在Markdown中复用内容，基于Sphinx生成受众专属文档？

Hey there! 作为技术文档撰写者，我完全懂你想要精简臃肿文档、高效复用内容的需求——毕竟没人想维护一堆重复的段落。结合你用Sphinx+Markdown+RST的工作流，给你几个简单易上手的方案，不用复杂开发就能实现：

1. 拆分内容+按需引入（最推荐，零门槛） #

把通用内容和特定受众的内容拆分成独立的Markdown文件，然后通过RST索引文件来组合它们：

• 比如：
  • 通用奶酪内容：general-cheese-docs.md（写Gouda、mozzarella这些通用部分）
  • 无乳制品专属内容：dairy-free-additions.md
  • 剩余通用内容：remaining-cheese-recipes.md
• 然后为不同受众创建专属的RST索引，比如给无乳制品用户的dairy-free-guide.rst：

  .. markdown-ingest:: :filename: ./general-cheese-docs.md
  .. markdown-ingest:: :filename: ./dairy-free-additions.md
  .. markdown-ingest:: :filename: ./remaining-cheese-recipes.md
  

• 给普通用户的RST就去掉dairy-free-additions.md的引入就行。

这种方法完全不用改原Markdown内容，只需要维护不同的RST索引，对非开发人员特别友好。

2. 用Sphinx条件标签控制内容显示 #

如果不想拆分太多文件，可以用Sphinx的only指令，在Markdown里嵌入简单的RST注释来控制哪些内容显示给特定受众：

• 在你的主Markdown文件里这么写：

  Gouda bavarian bergkase mozzarella...
  
  .. only:: dairy_free
     .. markdown-ingest:: :filename: ./dairy-free-content.md
  
  Cheesecake mozzarella cauliflower cheese...
  

• 构建文档时，通过命令行参数指定要激活的标签：

  sphinx-build -b html -D tags=dairy_free docs/ build/
  

• 不加-D tags=dairy_free的话，那段无乳制品内容就不会显示。

这个方法适合受众类型不多的场景，不用拆分文件，只需要构建时加个参数就行。

3. 纯Markdown嵌入语法（借助轻量扩展） #

如果你更习惯纯Markdown写法，可以用m2r2扩展（它能让Sphinx更好地兼容Markdown里的RST指令）：

• 先在环境里安装扩展：pip install m2r2
• 在Sphinx的conf.py里添加扩展：

  extensions = ['m2r2']
  

• 然后直接在Markdown里用include指令引入内容块：

  Gouda bavarian bergkase mozzarella...
  
  .. include:: ./dairy-free-content.md
  
  Cheesecake mozzarella cauliflower cheese...
  

总结 #

优先试试第一个方案，拆分内容后不仅复用性强，后续维护也更清晰，完全不用复杂配置。如果受众类型少，第二个方案更省事儿。

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