使用Markdown和Docbook编写Perl文档（包括POD）
内容提要
作者发布了多个CPAN模块，支持用Markdown或Docbook编写Perl文档，再合并为POD嵌入源码，并发布为静态HTML站点。其中Markdown::Pod::Embed负责转换嵌入，ASPEER::MakeMaker提供make doc等目标，Markdown::Publish支持Mkdocs、Docusaurus等引擎并推送至GitHub Pages或Cloudflare，Docbook::Convert可将Docbook文章转为Markdown。
延伸解读
Markdown 与 POD 的互补策略
文章指出 POD 是 Perl 生态的通用文档格式，但不易在 GitHub 等平台直接阅读。Markdown 则被前端原生渲染，便于浏览。作者通过 sidecar 文件（如 Client.pm.md）将 Markdown 转换为 POD 并嵌入源码，既保留了 POD 的兼容性，又让文档在仓库中可读。这种策略平衡了传统与现代工作流。
自动化文档构建与发布
通过 ASPEER::MakeMaker 扩展，可将文档合并和发布集成到 Makefile 中，例如 make doc 自动转换 sidecar 文件，make publish_gh-push 构建并推送静态站点。这减少了手动操作，适合持续集成。但需注意 markpod 会替换源码中现有 POD，使用前应备份或确认。
Docbook 的适用场景与转换
对于大型或复杂技术文档，Docbook 提供更丰富的语义结构，且可用 XXE XMLMind 等可视化编辑器。Docbook::Convert 模块能将 Docbook 文章转为 Markdown，进而通过标准工具链发布。这为需要严格文档结构的项目提供了灵活选择，但依赖 pandoc 等外部工具。
工具链的成熟度与维护
作者透露这些模块大多为人工编写，部分有 AI 辅助修复或扩展。Markdown::Publish 最初针对 MkDocs，后由 AI 添加多引擎支持。这表明工具链在持续演进，但用户需关注模块的更新状态和兼容性，尤其是对非 MkDocs 引擎的支持可能不如原生完善。
Q&A
如何用Markdown编写Perl模块的文档并嵌入到源代码中？
使用Markdown::Pod::Embed模块。安装后运行markpod命令，例如：markpod --inplace --nobackup --recursive lib bin，它会将Markdown边车文件（与源文件同名加.md后缀）转换为POD并追加到源文件中。注意：源文件中已有的POD会被替换。
ASPEER::MakeMaker::Markdown::Pod模块提供了哪些Makefile目标？
该模块提供make doc目标，用于将模块和脚本的Markdown边车文件转换为POD并嵌入源文件。如果检测到README.md，还会用pandoc将其转换为纯文本README。
Markdown::Publish支持哪些静态站点生成引擎？
支持Mkdocs Material、Docusaurus、Vitepress和Astro Starlight。
如何将Perl文档发布到GitHub Pages？
使用Markdown::Publish模块。安装后，运行markdown-publish build构建站点，markdown-publish serve本地预览，markdown-publish gh-push推送到GitHub Pages。也可以通过ASPEER::MakeMaker::Markdown::Publish模块运行make publish_gh-push。
Docbook::Convert模块有什么作用？
Docbook::Convert可以将Docbook文章转换为Markdown，然后通过标准工具链发布。它需要系统安装pandoc等二进制文件。
为什么选择Markdown而不是POD来编写Perl文档？
POD是Perl世界的通用格式，但在GitHub等现代版本控制系统中，Markdown能被前端浏览器原生渲染，而POD难以从源代码中直接解析，不利于用户快速理解模块功能。
