Markdown Preview Enhanced 电子书生成全攻略

Markdown Preview Enhanced 电子书生成全攻略

前言

Markdown Preview Enhanced 是一个功能强大的 Markdown 预览增强工具，它不仅提供了优秀的实时预览功能，还支持将 Markdown 内容导出为多种格式的电子书，包括 ePub、Mobi、PDF 和 HTML。本文将详细介绍如何使用该工具生成专业级电子书。

准备工作

安装 ebook-convert

电子书生成功能依赖于 Calibre 提供的 ebook-convert 工具，因此需要先安装 Calibre：

macOS 系统安装步骤

1. 下载 Calibre 应用
2. 将应用移动到 Applications 文件夹
3. 创建符号链接到系统路径：

sudo ln -s ~/Applications/calibre.app/Contents/MacOS/ebook-convert /usr/local/bin

Windows 系统安装步骤

1. 下载并安装 Calibre
2. 将 ebook-convert 添加到系统环境变量 PATH 中

电子书项目结构

一个标准的电子书项目通常包含以下结构：

• SUMMARY.md：主入口文件，包含书籍目录结构
• 各章节 Markdown 文件
• 静态资源（图片等）

示例 SUMMARY.md

---
ebook:
  theme: github-light.css
  title: Markdown 高级教程
  author: 技术专家
---

# 前言

这里是书籍的前言部分...

# 目录

- [第一章 基础](/chapter1/README.md)
  - [Markdown 简介](/chapter1/intro.md)
  - [核心语法](/chapter1/syntax.md)
- [第二章 高级功能](/chapter2/README.md)
  - [图表支持](/chapter2/diagrams.md)

注意：文件中的最后一个列表会被自动识别为目录结构。

电子书配置详解

基础元数据配置

在 Markdown 文件的 front-matter 中可以配置丰富的电子书元数据：

ebook:
  title: "深入理解 Markdown"
  authors: "作者1 & 作者2"
  cover: "/path/to/cover.png"
  language: "zh-CN"
  publisher: "技术出版社"
  isbn: "978-7-121-12345-6"
  tags: "技术,编程,Markdown"
  rating: 5

排版与样式控制

ebook:
  base-font-size: 12    # 基础字体大小(单位:pt)
  line-height: 1.5      # 行高
  margin: [50, 60, 50, 60]  # 页边距(上,右,下,左)
  disable-font-rescaling: false  # 是否禁用字体缩放

导出不同格式电子书

导出 ePub 电子书

ebook:
  epub:
    no-default-epub-cover: false  # 是否禁用默认封面
    pretty-print: true            # 美化输出

导出 PDF 文档

ebook:
  pdf:
    paper-size: "a4"              # 纸张大小
    default-font-size: 11         # 默认字体大小
    header-template: "<span>第 _PAGENUM_ 页</span>"
    footer-template: "<div>©2023 技术出版社</div>"

导出 HTML 单文件

ebook:
  html:
    cdn: true  # 使用CDN加载资源

高级功能

自定义转换参数

如果需要使用 ebook-convert 的特殊参数，可以通过 args 配置：

ebook:
  args: ["--embed-all-fonts", "--preserve-cover-aspect-ratio"]

保存时自动导出

配置自动导出功能后，每次保存 Markdown 文件时都会自动生成电子书：

export_on_save:
  ebook: ["pdf", "epub"]  # 同时导出PDF和ePub

技术限制与注意事项

1. 图表支持：目前仅支持 Viz 生成的图表，Mermaid 和 PlantUML 的 SVG 图表无法在电子书中正常显示
2. 数学公式：仅支持 KaTeX 渲染，且在 iBooks 中可能显示不正常
3. 代码块执行：不支持代码块的执行功能
4. PDF/Mobi：这两个格式的生成可能存在一些稳定性问题

最佳实践建议

1. 对于技术文档，建议优先使用 ePub 格式
2. 需要打印时选择 PDF 格式
3. 简单分享可使用 HTML 单文件格式
4. 封面图片建议使用 2:3 的比例
5. 中文文档确保设置正确的语言标识 zh-CN

通过合理配置 Markdown Preview Enhanced 的电子书生成功能，开发者可以轻松将技术文档、教程等内容转换为专业格式的电子书，便于分发和阅读。