MDBook EPUB 后端

(Rendered Docs)

一个实验性的 mdbook 后端，可以将您的文档渲染为 EPUB 文件，适用于在电子阅读器和其他类似设备上查看。

警告：尚未准备就绪。可能会吃掉您的衣物。

注意：目前默认样式表相当简单，主要是将各种设备上使用的样式重置为已知默认值。这个默认值不是很美观，因此您可能希望包含自己的样式表。

入门

在您可以使用 EPUB 后端之前，您需要实际安装它

$ cargo install mdbook-epub

接下来，您需要让 mdbook 知道使用替代渲染器，通过更新您的 book.toml 文件。这通过简单地添加一个空的 output.epub 表来完成。

[book]
title = "mdBook Documentation"
description = "Create book from markdown files. Like Gitbook but implemented in Rust"
author = "Mathieu David"

[output.html]
mathjax-support = true

+ [output.epub]

现在一切设置完毕，只需像往常一样运行 mdbook，输出目录（默认为 book/epub/）现在应包含一个名为 mdBook Documentation.epub（用您的书名替换）的额外文件。

mdbook-epub 可执行文件可以以“独立”模式运行。这是后端可以在不通过 mdbook 调用的情况下使用的地方，如果您只想渲染 EPUB 文档，这很有用。

$ mdbook-epub -s ./path/to/book/dir
$ mdbook-epub --standalone ./path/to/book/dir

配置

目前的配置相当简单。

识别的选项

additional-css：包含要包括的 CSS 样式表的路径列表。

use-default-css：控制是否包含默认样式表。

cover-image：电子书的封面图片文件路径。

additional-resources：要添加到 EPUB 的文件路径列表，例如字体。它们将以路径 OEBPS/<filename> 添加。

no-section-label：在目录列表中，不要在章节标题前加其节号。

curly-quotes：启用将直引号 'x' 和 "x" 转换为 ‘x’ 和 “x”（即智能引号）。

[output.epub]
additional-css = ["./path/to/main.css"]
use-default-css = false
cover-image = "ebook-cover.png"
additional-resources = ["./assets/Open-Sans-Regular.ttf"]
no-section-label = true
curly-quotes = true

日志记录，查看进度

为了将日志记录到屏幕，您需要将环境变量 RUST_LOG 设置为 debug 或 info。

在 Linux 和 macOS 上，可以通过以下方式完成

RUST_LOG=debug  mdbook-epub

在 Windows CMD 中，您需要在单独的一行上设置它

set RUST_LOG=debug
mdbook-epub

计划中的功能

以下功能是计划中的（勾选框表示已完成）。这个列表绝对不是完整的，因此非常欢迎功能请求！

• 使用纯章节内容创建有效的 EPUB 文件
• 生成基本的目录
• 嵌套章节 - 目前它们都被插入到顶级
• 包含默认的 CSS 样式表（master.css）
  • 实际上使该样式表足够美观，适合人类使用
• 包含用户定义的样式表和主题
• 允许用户通过提供自己的模板来调整生成的页面
• 确保生成的文档可在以下平台查看
  • 亚马逊Kindle
  • Sony PRS-T3

贡献

此后端仍在开发阶段，因此许多功能尚未实现。如果您有想法，请创建 问题跟踪器 上的问题！