Markdown 转 reStructuredText 工具

A：reStructuredText 是 Python 社区广泛使用的轻量级标记语言，由 Docutils 项目定义和维护。它是 Sphinx 文档生成器的默认源格式，被广泛用于 Python 官方文档、NumPy、Django、Read the Docs 等技术文档平台。与 Markdown 追求简洁不同，rST 的设计目标是功能完整和高度可扩展。它支持指令（directives）和角色（roles）系统，可以定义代码高亮、交叉引用、术语索引等高级文档功能。rST 比 Markdown 语法更加严格和规范，适合编写结构复杂、需要自动生成导航的技术文档。

A：两者在设计哲学和语法细节上存在显著差异。设计哲学方面，Markdown 追求简洁易读，rST 追求功能完整与可扩展性。标题语法方面，Markdown 使用 # 前缀标注标题层级，rST 使用等长的下划线或上划线装饰字符。代码块方面，Markdown 使用三个反引号围栏包裹，rST 使用 .. code-block:: 指令定义。链接语法方面，Markdown 写作 [text](url)，rST 写作反引号尖括号格式。扩展性方面，rST 拥有强大的指令系统（如 .. note::、.. warning::），而 Markdown 依赖各家实现的变体扩展。表格方面，Markdown 使用管道符分隔的简单表格语法，rST 支持 grid_table 和 simple_table 等多种表格指令。

A：在以下几种常见场景中需要进行 Markdown 到 rST 的转换。如果您正在使用 Sphinx 构建技术文档，Sphinx 默认使用 rST 作为源格式，需要将已有的 Markdown 文档转换为 rST 才能纳入 Sphinx 的文档构建流程。如果您需要向 Python 开源项目贡献文档，而该项目采用 Sphinx + rST 的文档体系，则需要按项目规范提供 rST 格式的文档内容。如果您需要在 Read the Docs 平台上发布文档，虽然该平台通过 MyST 扩展支持 Markdown，但使用原生 rST 格式能获得更完整的 Sphinx 功能支持。此外，rST 对复杂文档结构（如交叉引用、自动 API 文档、多层级目录树）的支持比 Markdown 更完善，对于大型技术文档项目而言更加合适。

A：本工具支持标准 Markdown 和 GitHub Flavored Markdown（GFM）中的常用语法元素，包括：标题（h1-h6，使用 # 前缀）、粗体（**text**）和斜体（*text*）、行内代码（反引号包裹）、围栏式代码块（三个反引号，支持语言标识）、无序列表和有序列表（支持嵌套）、引用块（使用 > 前缀）、链接（内联式 [text](url) 和引用式）、图片（）、水平分隔线（--- 或 ***）、以及 GFM 风格的管道表格。部分高级特性如脚注、任务列表、定义列表的转换可能不够完美，建议转换后进行人工校对。

A：由于 Markdown 和 reStructuredText 在设计理念和功能集上存在本质差异，某些元素无法在转换过程中完美映射。具体局限性包括：Markdown 的引用式链接（如 [text][ref]）在转换时会被展开为内联链接，原始的引用式定义将被丢弃；GitHub Flavored Markdown 的删除线语法在标准 rST 中没有直接对应，转换后文本将被原样保留但不带有删除线效果；文档中内嵌的 HTML 标签在 rST 中通常不被直接支持，需要手动替换为对应的 rST 指令或角色；复杂的嵌套表格在 rST 中的渲染效果可能与原始 Markdown 有差异，列宽和对齐可能需要手动调整。总体而言，转换结果应作为文档迁移的起点，根据实际项目需求进行必要的微调和完善。

A：rST 标题使用装饰字符（如 =、-、~、^、"、' 等）标注标题层级，装饰线必须与标题文本等长（或更长）。标题可以使用上方装饰线、下方装饰线或上下双侧装饰线。本工具的默认映射规则为：Markdown 的 h1 转换为 rST 的上下双侧 = 线装饰，h2 转换为下方 = 线，h3 转换为下方 - 线，h4 转换为下方 ~ 线，h5 转换为下方 ^ 线，h6 转换为下方双引号线。在同一个文档中，不同的装饰字符代表不同的层级，因此层级的先后顺序由文档中首次出现的装饰字符决定。如果您的项目对标题装饰字符有特殊约定，可以在转换后手动调整装饰字符的分配。

A：Sphinx 是基于 Docutils 的文档生成工具，原生使用 reStructuredText 作为标记语言。可以说 rST 是 Sphinx 的源代码格式，而 Sphinx 是 rST 的编译器和增强器。Sphinx 在 Docutils 提供的基础 rST 解析和转换能力之上，扩展了大量特有指令和角色：.. toctree:: 用于定义文档间的层级目录关系，.. automodule:: 用于从 Python 代码自动提取 API 文档，:ref: 用于创建文档间的交叉引用，.. image:: 和 .. figure:: 用于嵌入图片并控制排版。本工具生成的是标准 rST 内容，可被 Sphinx 直接识别和渲染。转换后的 rST 文件放入 Sphinx 项目目录并在 toctree 中注册后，即可通过 Sphinx 构建为 HTML、PDF 等多种输出格式。

A：如果需要批量转换多个 Markdown 文件到 reStructuredText 格式，推荐使用 Pandoc 命令行工具。安装 Pandoc 后，可以使用 pandoc input.md -o output.rst 命令进行单文件转换，也可以结合 shell 脚本或 Makefile 实现批量处理。例如在 Linux 或 macOS 系统中可以使用 for f in *.md; do pandoc "$f" -o "${f%.md}.rst"; done 命令将当前目录下所有 .md 文件转换为 .rst 文件。Pandoc 相比在线工具的优势在于支持更全面的语法覆盖、可自定义转换模板、适合自动化流水线集成。而本在线工具更适合快速单篇转换、实时预览对比、以及学习两种格式语法差异的场景。对于中等规模的文档迁移项目，建议先使用本在线工具熟悉转换效果，再使用 Pandoc 进行批量处理。

A：根据实际使用经验，转换后的 rST 文档通常需要在以下方面进行手动检查和调整。标题装饰线方面，确认装饰字符的层级分配是否符合项目规范，必要时统一调整装饰字符。代码块方面，检查代码块的语言标识是否正确传递，部分语言标识在 rST 中的名称可能与 Markdown 中不同。链接方面，确认内联链接格式是否正确，特别是包含特殊字符的 URL。表格方面，检查复杂表格的渲染效果，特别是合并单元格和自定义对齐的表格可能需要重写为 rST 原生表格语法。图片方面，确认图片路径在 Sphinx 项目中可正确解析。文档结构方面，如果需要使用 Sphinx 的 toctree、交叉引用等高级功能，需要手动添加相应的指令和角色。总体而言，对于简单的 Markdown 文档，转换质量通常很高，只需少量微调即可直接使用。