mdbook-pandoc  

一个将大部分渲染过程外包给 pandoc 的 mdbook 后端。通过依赖 pandoc，支持许多输出格式，尽管该项目主要是针对 LaTeX 开发的。

请参阅 渲染的书籍 以查看渲染书籍的示例。

安装

• 安装 mdbook

• 安装 mdbook-pandoc

  要安装发布到 crates.io 的最新版本

  cargo install mdbook-pandoc
  

  安装 GitHub 上提交的最新版本

  cargo install --git https://github.com/max-heller/mdbook-pandoc.git mdbook-pandoc
  

• 安装 pandoc

  注意: mdbook-pandoc 与 Pandoc 2.10.1 或更高版本配合最佳。旧版本（如 2.8 或更低版本）部分支持，但会导致输出质量下降。

  如果您已安装 Pandoc 的旧版本（特别是，在 23.04 之前的 Ubuntu 版本中，其软件包仓库中的 Pandoc 版本低于推荐版本），请考虑从 Pandoc 的安装页面下载较新版本。

入门

通过更新您的 book.toml 文件来指导 mdbook 使用 mdbook-pandoc。以下示例配置 mdbook-pandoc 以使用 LaTeX（必须 安装）生成书的 PDF 版本。要生成其他输出格式，请参阅 配置。

[book]
title = "My First Book"

+ [output.pandoc.profile.pdf]
+ output-file = "output.pdf"
+ to = "latex"

运行 mdbook build 将会将渲染后的书籍写入 pdf/output.pdf，保存到 mdbook-pandoc 的 构建目录（如果配置了多个渲染器则为 book/pandoc；否则为 book）。

配置

由于 mdbook-pandoc 通过 pandoc 支持许多不同的输出格式，因此它必须在书籍的 book.toml 文件中的 [output.pandoc] 表中配置，以将书籍渲染为一种或多种格式。

配置围绕 输出配置文件 展开，这是 mdbook-pandoc 将作为 默认文件 传递给 pandoc 的命名选项包，以将书籍渲染为特定的格式。每个配置文件的输出将写入与配置文件同名的子目录中，该子目录位于 mdbook-pandoc 的顶级 构建目录（如果配置了多个渲染器则为 book/pandoc；否则为 book）。

以下描述了可用选项的一个子集

注意： Pandoc 从书籍的根目录（包含 book.toml 的目录）运行。因此，配置中的相对路径（例如 include-in-header、reference-doc 的值）应该相对于书籍的根目录编写。

[output.pandoc]
hosted-html = "https://doc.rust-lang.net.cn/book" # URL of a HTML version of the book

[output.pandoc.code]
# Display hidden lines in code blocks (e.g., lines in Rust blocks prefixed by '#').
# See https://rust-lang.github.io/mdBook/format/mdbook.html?highlight=hidden#hiding-code-lines
show-hidden-lines = false

[output.pandoc.profile.<name>] # options to pass to Pandoc (see https://pandoc.org/MANUAL.html#defaults-files)
output-file = "output.pdf" # output file (within the profile's build directory)
to = "latex" # output format

# PDF-specific settings
pdf-engine = "pdflatex" # engine to use to produce PDF output

# `mdbook-pandoc` overrides Pandoc's defaults for the following options to better support mdBooks
from = "commonmark" # source format; extensions enabled/disabled through this option are preserved
file-scope = true # parse each file individually before combining
number-sections = true # number sections headings
standalone = true # produce output with an appropriate header and footer
table-of-contents = true # include an automatically generated table of contents

# Arbitrary other Pandoc options can be specified as they would be in a Pandoc defaults file
# (see https://pandoc.org/MANUAL.html#defaults-files) but written in TOML instead of YAML...

# For example, to pass variables (https://pandoc.org/MANUAL.html#variables):
[output.pandoc.profile.<name>.variables]
# Set the pandoc variable named 'variable-name' to 'value'
variable-name = "value"

功能

• CommonMark + 由 mdBook 启用的扩展
  • 删除线（例如 ~~crossed out~~）
  • 脚注
  • 表格
  • 任务列表（例如 - [x] Complete task）
  • 标题属性（例如 # Heading { #custom-heading }）
• 目录
• 在解析链接时考虑 [output.html.redirect]
• 将 Font Awesome 4 图标（例如 <i class="fa fa-github"></i>）转换为 LaTeX