文档编写、审阅与发布

目标与适用范围

先从代码、PDF 或 HTML 提取资料，再完成 Markdown 整理、合并、预览和发布导出。
本指南将当前任务范围转化为可复核的交付结果。请保留源文件、中间产物和关键判断，让后续协作者能够理解检查了什么以及为什么这样处理。

准备证据并作出选择

• 先确认每个章节的权威来源是代码注释、生成的 API 结构、普通 PDF、扫描 PDF 还是现有 HTML。

• 编写前先决定交付目标：可审阅 Markdown、HTML 页面、PDF 文档，或打包后的发布资料。

• 收集必须保留下来的章节、示例、链接和版本说明。

• 决策点: 来源到底是什么格式？. 根据真实来源选择提取工具，不要把所有输入都硬塞进同一种转换路径。

• 决策点: 最终发布物是什么？. 如果目标是 HTML、PDF 或审阅包，预览和导出步骤的重点会不同。

• 决策点: 发布前需要整理哪些结构问题？. 先统一标题、列表、表格和链接，再预览，避免把本可修正的结构问题冻结进导出结果。

按步骤完成工作流

1. 提取源资料

从代码注释、API 结构、PDF、扫描 PDF 或现有 HTML 中提取可复用内容，让初稿建立在真实资料上，而不是人工重写。 使用 docstring-extractor, api-doc-generator, pdf-to-markdown, pdf-to-structured-markdown-converter, scanned-pdf-ocr-to-markdown, html-to-markdown.

2. 组装初稿

合并提取结果，在需要比较的地方补充表格，并把列表整理成一致的编辑结构。 使用 markdown-merger, markdown-table-generator, markdown-list-formatter.

3. 审阅链接与覆盖范围

检查外部引用并打包审阅材料，让缺链、重复段落和版本说明可以一起核对。 使用 markdown-link-extractor, markdown-report-bundler.

4. 预览发布版本

在导出前渲染文档，提前发现标题层级、格式断裂和版面问题，此时源 Markdown 仍然容易修订。 使用 markdown-preview.

5. 导出并交付

按约定生成 HTML 或 PDF；如果需要品牌化或更适合打印的效果，再应用 PDF 主题包。 使用 markdown-to-html, markdown-to-pdf-converter, markdown-to-pdf-theme-pack, doc-comment-to-pdf-docs.

交付前验收结果

• 每个章节都能追溯到明确来源，并被整理成连贯 Markdown，而不是零散提取文本。
• 合并后的文档结构完整，步骤非空，且需要保留的链接、表格和列表都可审阅。
• 预览结果证明文档阅读顺序和版式正确。
• 最终 HTML、PDF 或打包产物符合约定的发布目标。

常见问题

• PDF 提取是不是应该单独成一个工作流？ 这里不需要。PDF 提取只是取材步骤，最终目标仍是形成可发布文档。
• 什么时候用 OCR，而不是普通 PDF 转 Markdown？ 当 PDF 是扫描件或页面主要是图片，文本并非可直接选择时，应优先使用 OCR。
• HTML 和 PDF 都要导出吗？ 不一定。应先按受众决定最终交付物，再围绕对应版式和链接行为做审阅。
• Markdown 看起来已经整洁，为什么还要预览？ 渲染后才能暴露标题层级、表格溢出和链接格式问题，纯源码检查很容易漏掉。