sphinx-mdinclude

Sphinx扩展，用于包含或编写Markdown格式的页面。

sphinx-mdinclude是一个简单的Sphinx扩展，它允许在reStructuredText中包含Markdown文档。它提供.. mdinclude::指令，并自动将Markdown文档的内容转换为reStructuredText格式。

sphinx-mdinclude是基于m2r和m2r2的分支，仅专注于提供Sphinx扩展。

功能

• 基本Markdown和一些扩展（见下文）
  • 行内/块级原始HTML
  • 代码块
  • 表格
  • 脚注（[^1]）
• 行内/块级rst标记
  • 单行/多行指令（.. directive::）
  • 行内角色（:code:`print(1)` ...）
  • 引用链接（see `ref`_）
  • 脚注（[#fn]_）
  • 受recommonmark启发的数学扩展
• Sphinx扩展
  • 为Sphinx添加Markdown支持
  • mdinclude指令，用于从md或rst文件中包含Markdown
  • 选项将相对链接解析为ref和doc指令（md_parse_relative_links）

限制

• 在rst的指令中，Markdown不可用。请使用rst编写。
• 表格列对齐不支持。（rst不支持此功能）
• 带有上划线和下划线的标题不支持。
  • 带有下划线的标题是OK的
• Rst标题标记目前是硬编码的，无法更改。
  • H1: =, H2: -, H3: ^, H4: ~, H5: ", H6: #

安装

需要 Python 3.6 或更高版本。

pip install sphinx-mdinclude

使用方法

在您的 Sphinx conf.py 文件中添加以下行

extensions = [
    ...,
    'sphinx_mdinclude',
]

具有 .md 扩展名的 Markdown 文件将被 Sphinx 加载并使用，类似于其他任何 .rst 文件。

要在其他文件中包含 Markdown 文件，请使用 .. mdinclude:: <filename> 指令。这将应用从 Markdown 到 reStructuredText 格式的转换。

许可协议

sphinx-mdinclude 由 Hiroyuki Takagi、CrossNox 和 Amethyst Reese 拥有版权，并使用 MIT 许可证许可。我正在以开源许可证提供此存储库中的代码。这是我的个人存储库；您获得的我的代码的许可证来自我，而不是我的雇主。有关详细信息，请参阅LICENSE 文件。