用途
publication-converter 用于将 Markdown 文档转换为 EPUB 电子书格式，把结构化 Markdown 转换为排版专业的电子书。适合将研究文档、博客文章、文章或对话摘要转换为可跨设备阅读的电子书。
主要能力
技能接受多种形式的 Markdown 内容，生成符合规范的 EPUB3 文件，可在主流电子书阅读器上使用，包括 Apple Books、Amazon Kindle（通过 Kindle for Mac/Windows/iOS/Android）、Google Play Books、Kobo 及其他 EPUB 阅读器和任意标准 EPUB 阅读器。
支持的输入方式：
- 方式一：直接在消息中提供原始 Markdown 文本。
- 方式二：提供待转换的 Markdown 文件路径。
工作方式
Markdown 解析：分析 Markdown 并自动执行以下处理——
- 将 H1 标题（#）视为章节边界
- 将 H2 标题（##）视为章节内的小节标题
- 保留格式（粗体、斜体、链接、列表、代码块）
结构生成：创建规范的 EPUB 结构——
- 根据章节自动生成目录
- 生成导航文档（EPUB3 标准）
- 生成元数据（标题、语言等）
文件创建：生成可下载并使用的有效 EPUB3 文件。
支持的 Markdown 元素
- 标题：
# H1至###### H6，完整支持，自动生成目录 - 粗体：
**text**或__text__，完整支持 - 斜体：
*text*或_text_，完整支持 - 链接：
[text](url)，完整支持，在电子书中可点击 - 列表：
- item或1. item，完整支持，支持嵌套列表 - 代码块：```language，增强支持，可语法高亮、等宽字体
- 行内代码：
code，增强支持，带样式背景和边框 - 表格：Markdown 表格，增强支持，样式化表头、交替行
- 引用：
> quote，完整支持，左侧边框样式 - 水平分割线：
---或***，完整支持
高级功能
增强的代码块支持：使用优质等宽字体（SF Mono、Monaco、Fira Code、Consolas 等），带样式背景（浅灰色背景与蓝色强调边框），支持语言检测（在 ``` 后指定语言以备将来语法高亮），HTML 字符安全转义，长行支持水平滚动。
增强的表格支持：样式化表头（蓝色背景、白色文字），交替行（斑马纹便于阅读），单元格内边距舒适，单元格内支持行内格式（代码、粗体、斜体、链接），响应式适配不同屏幕尺寸。
自定义标题与元数据：可指定 EPUB 元数据，包括书名（默认取第一个 H1 标题）、作者名、语言、出版日期。
章节组织：自动从以下内容检测章节——H1 标题（#）作为主要章节分隔，H1 之间的逻辑内容分段，章节间自动分页。
样式：生成的 EPUB 使用简洁、易读的默认样式，遵循阅读器的字体偏好，适配所有屏幕尺寸，保持恰当的间距和层级，包含合适的边距和内边距。
使用示例
- 示例一：转换博客文章——“将这篇 Markdown 博客文章转换为 EPUB：如何构建一个简单的 Web 服务器……”
- 示例二：转换研究摘要——“我用 Markdown 格式记录了研究笔记，请将它们转换为 EPUB 电子书……”
- 示例三：转换对话摘要——“将我们目前的对话总结为 Markdown 并转换为 EPUB 以便参考”
输出
技能生成可下载的 EPUB 文件，包含专业排版、自动目录、规范的章节结构，并支持上述各 Markdown 格式元素。
技术细节
- 格式：EPUB3（兼容所有现代阅读器）
- 编码：UTF-8
- HTML 版本：XHTML 1.1
- CSS 支持：响应式样式
下载 EPUB
生成后文件可供下载。你可以将 EPUB 下载到电脑，用偏好的电子书阅读器打开，传输到 Kindle、iPad 或其他设备，或通过邮件或云端直接上传至 Kindle。
使用建议
- 使用规范的 Markdown 结构：遵循标准惯例（H1 用作标题，H2 用作小节）时效果最佳。
- 清晰的章节分隔：使用 H1 标题清楚标记章节划分。
- 描述性标题：标题会成为目录，因此应清晰且具有描述性。
- 内容组织：在标题之间逻辑地放置内容。
- 支持的格式：坚持使用基础 Markdown 格式，以获得跨阅读器的最佳兼容性。
常见问题排查
- EPUB 无法打开：确保 Markdown 格式正确，检查链接的括号是否匹配以及语法是否正确。
- 目录为空：确保 Markdown 中包含用于定义章节的 H1 标题。
- 排版看起来不同：EPUB 阅读器会应用各自的字体和样式，这是正常且预期的行为。
脚本
- epub_generator.py —— 核心 EPUB 文件创建与排版
- markdown_processor.py —— Markdown 解析与结构提取
未来增强
- 带自定义图片的自动生成封面页
- Kindle 专用优化（.mobi 格式）
- 按用户偏好自定义 CSS 样式
- 多文档合并
- 图片嵌入与优化
- 高级元数据支持