md写图文后快速转为电子书的方式

脑内BUG实录
字数统计: 1.7k   |   阅读时长≈ 6 分钟

大概算一篇随笔，在寻找用Markdown写图文内容可以快速转换成电子书的方式。对程序员来说还是md最好用了。粗略研究了一下ghmdlib、mark-deco、Pandoc 、**MkDocs **、md2html。

ghmdlib

ghmdlib是个挺单纯冷门的小工具，很少看到有人使用。生成的 HTML 在视觉和语法渲染上完全复刻了 GitHub 的样式，能离线使用，主要适合需要离线、可移植的文档输出作者。

官网：https://pypi.org/project/ghmdlib/#description

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
ghmdlib>ghmd --help
usage: ghmdlib [--dark] [--light] [--download] [--embed-css] [--no-gfm] [--offline] [--preview] [-d] [-h] [-V]
               PATH [PATH ...]

A Markdown to GitHub-style HTML file conversion utility.

positional arguments:
  PATH           Path(s) to the Markdown files to be converted.

options:
  --dark         Use a dark HTML theme. (Default)
  --light        Use a light HTML theme.

  --download     Download the latest CSS files from GitHub. These files are used for offline mode.
  --embed-css    Embed the CSS into the HTML file instead of using the <link> tag.
  --no-gfm       Use plain Markdown mode instead of GitHub Flavored Markdown (gfm).
  --offline      Keep offline.
                 - Uses cached CSS files and local libraries for the HTML conversion
                   rather than the GitHub API.
  --preview      Auto-open each converted HTML file in a web browser for viewing.

  -d, --debug    Display debugging output to the terminal.
  -h, --help     Display this help and usage, then exit.
  -V, --version  Display the version, then exit.

ghmdlib v0.1.0

1. 指定要转换的文件（必填）

  • PATH [PATH ...]
    你需要在这里填写要转换的 Markdown 文件的路径（可以同时指定多个文件，用空格隔开）。
    例如：ghmd README.md docs/guide.md

2. 控制生成的 HTML 外观（主题）

  • --dark
    使用深色主题（这是默认选项，不写也会是深色）。
  • --light
    使用浅色主题。
    两者互斥，只能选一个。

3. 网络与转换方式

  • --offline
    离线模式：不调用 GitHub API，而是使用本地缓存的 CSS 和内置转换器生成 HTML。
    👉 这是你之前遇到 API 错误时最推荐的选项，可以完全避免网络问题。
  • --no-gfm
    不使用 GitHub Flavored Markdown（GFM），即仅用普通 Markdown 语法（不支持表格、任务列表等 GFM 扩展）。默认是启用 GFM 的。
  • --download
    下载最新的 GitHub CSS 文件到本地（供离线模式使用）。通常你只需要在初次使用离线模式前执行一次，之后就能一直用本地样式。

4. 生成 HTML 文件的处理

  • --embed-css
    将 CSS 样式直接嵌入 HTML 文件内部，而不是通过 <link> 标签外链。
    这样生成的 HTML 是一个独立的单文件，方便分享（但文件体积会稍大）。
  • --preview
    转换完成后自动用默认浏览器打开生成的 HTML 文件。

示例：

1
2
3
ghmd README.md --light          # 转换单个文件，使用浅色主题
ghmd file1.md file2.md --dark   # 转换多个文件，使用深色主题（默认）
ghmd docs/*.md --offline        # 使用通配符转换 docs 下所有 md 文件，离线模式

假设希望用 Markdown 写教程，最终输出一个 独立的、GitHub 风格的单文件 HTML（带目录），可以：

  1. 使用 Markdown 扩展生成目录
    在 Markdown 文件中加入 [TOC]（某些渲染器支持），或使用 pandoc 生成目录。

  2. 将多个 Markdown 文件合并

    1
    pandoc chapter1.md chapter2.md appendix.md -o full.md

  3. 用 ghmdlib 转换为 HTML

    1
    ghmd full.md --embed-css --light --preview

    这样得到的是一个完整的、带有 GitHub 样式的 HTML 文件，适合在线阅读或分发。

mark-deco

mark-deco 是一个用 TypeScript 编写的、灵活的 Markdown 转 HTML 库，可以理解为之前提到的 ghmdlib 的“增强版”或“功能更全的同类工具”。都是将 Markdown 转换为 HTML，但 mark-deco 的功能更丰富，定制性也更强。

官网：https://www.npmjs.com/package/mark-deco

mark-deco 的出现，其实是为了满足比 ghmdlib 更复杂的定制需求。如果遇到以下情况，可以考虑用它来替代 ghmdlib：

  1. 需要处理文档元数据：你的 Markdown 文件开头有 --- title: ... --- 这样的 Frontmatter 信息，需要在转换时提取出来。
  2. 需要嵌入图表或外部内容：文档里包含流程图（Mermaid）、需要自动解析的链接（oEmbed），希望这些能自动变成可交互的 HTML 元素。
  3. 需要将转换功能集成到自己的项目里：你想在自己写的 Node.js 脚本或网页应用里，实现 Markdown 转 HTML 的功能，并且希望对转换过程进行编程控制。

Pandoc

Pandoc适合单篇文档需要多种输出格式（PDF、EPUB、Word）。它的核心功能是在几十种格式之间相互转换，比如 Markdown → HTML、Markdown → PDF、Markdown → EPUB、Markdown → Word 等等。对于需要跨格式转换文档的开发者、作者或学者来说，Pandoc 提供了一种简便且强大的解决方案。

它支持：

  • 文本格式：如 Markdown、LaTeX、reStructuredText、HTML。
  • 办公文档格式：如 Microsoft Word (.docx)、OpenDocument 格式（.odt）。
  • 电子书格式：如 EPUB 和 MOBI。
  • PDF：通过与 LaTeX 配合使用，可以输出高质量的 PDF 文档。

官网：https://pandoc.org/

中文官网：https://pandoc.cn/

在线尝试：https://pandoc.org/try/

官方下载：https://pandoc.org/installing.html

示例：

1
2
3
4
5
6
7
8
9
10
11
# Markdown → HTML（独立完整文档）
pandoc input.md -s -o output.html

# Markdown → PDF
pandoc input.md -o output.pdf

# 合并多个文件 → EPUB 电子书
pandoc chapter1.md chapter2.md -o book.epub

# LaTeX → Word
pandoc paper.tex -o paper.docx

下载

1
winget install --source winget --exact --id JohnMacFarlane.Pandoc

或

1
choco install rsvg-convert python miktex

使用

具体的使用还是挺麻烦的，github已有的css主题样式不够好看或有些许配置问题。推荐自定义css。

具体的电子书使用，需要文件目录结构为：

1
2
3
4
01-intro.md
02-chapter1.md
03-chapter2.md
04-appendix.md

**MkDocs **

MkDocs倒是一个比较热门的 静态站点生成器，属于静态站点生成器（SSG）的生态了，与依赖 Node.js 环境的 Hexo 以及借助 Go 语言编译的 Hugo 不同，Mkdocs 仅需基础的 Python 环境即可运行，被很多知名开源项目选中，用于搭建和项目相关的文档网站。它的优势是快速构建一个结构清晰、便于阅读的静态网站（或者说在线电子书）。

官网 中文文档 教程文档

如果使用 Markdown 来写作或记录，且不想花费过多时间和精力在琐碎的站点设计上，MkDocs 是个不错的选择。网络上有关MkDocs的教程有很多，这里就不介绍了。

md2html

md2html是”预览优先的实时转换器”。最突出的特点是实时预览功能。运行后它会启动一个本地服务器，你修改 Markdown 文件，浏览器会自动刷新。这对于边写边看的场景非常友好。

比较知名可以直接搜得到，官网也可直接试用，这里不过多赘述。使用需要先安装go环境。

官网：https://md2html.com/

https://pkg.go.dev/github.com/tmc/misc/md2html

  • 版权声明： 本博客所有文章除特别声明外，著作权归作者所有。转载请注明出处！

You Found Me.

支付宝
微信