mdbook-latex

• Rust 书架状态
• 安装
• 卸载
• 主要依赖
• 它是如何工作的？
• 贡献
  • 我发现了一个问题。我应该为 mdbook-latex 或 md2tex 创建一个问题吗？
• 我们稳定了吗？
• 另请参阅
• mdbook-latex 无法构建我的书籍！现在怎么办？ >:(
  • 自动方法
  • 手动方法
  • 最后
• 二进制发布状态

一个用于生成 LaTeX 和 PDF 文档的 mdbook 后端。使用 md2tex 进行 Markdown 到 LaTeX 的转换，但旨在允许使用替代的 Markdown 到 LaTeX 转换器。如果您开发了您自己的 Markdown 到 LaTeX 转换器，我很乐意与您交谈或分享想法！我在 [email protected]。

警告：尚未稳定——可能会吃掉、撕碎并原子化您的衣物！请参阅 我们稳定了吗？ 部分以获取生产发布的路线图。

失败：如果 mdbook-latex 失败，请参阅 mdbook-latex 无法构建我的书籍！现在怎么办？ >:(。如果您有任何问题或建议，我也可通过 电子邮件 联系我！

Rust 书架状态

• ✅ 编译成功
• 🍊 编译但有警告/错误
• ❌ 编译失败/尚未尝试

安装

首先，安装以下两个程序

• Rust
• mdbook

然后，为了安装 mdbook-latex，在 shell 中输入以下命令

cargo install mdbook-latex

最后，将以下 toml 配置添加到 book.toml 中。

[output.latex]
latex    = true  # default = true
pdf      = true  # default = false
markdown = true  # default = false

下一个 mdbook build 命令将在 book/latex/ 目录中生成 LaTeX 和 PDF 文件（以及你的 mdbook 的 markdown 文件）。

卸载

要卸载 mdbook-latex，在 shell 中输入以下命令

cargo uninstall mdbook-latex

然后在 book.toml 中删除以下 [output.latex] 配置

- [output.latex]
- latex    = true
- pdf      = true
- markdown = true

主要依赖

mdbook-latex 基于 一些非常出色的项目，包括

• pulldown-cmark：解析 markdown 源 AST。
• Tectonic：从转换后的 LaTeX 代码创建最终的 PDF 文件。
• md2tex：将 markdown 源转换为 LaTeX。这是 md2pdf 的分支，一个将 markdown 代码转换为 LaTeX 和 PDF 的优秀工具。我希望最终能够将一些更新回传给上游。 md2tex 和 mdbook-latex 是同时开发的，但它们是独立的程序。因此，如果有人想使用替代的 markdown 到 tex 转换器，他们应该能够轻松地将它集成到 mdbook-latex 中。

它是如何工作的？

总的来说，从 mdbook 源到 PDF 输出的过程有三个步骤，或“转换”

1. mdbook 源到 JSON 组织的 markdown （mdbook-latex）：从 mdbook 获取 JSON 格式的数据。分别调用 md2tex 和 tectonic 进行 LaTeX 和 PDF 生成。
2. markdown 到 LaTeX （md2tex）：将 markdown 输入转换为 LaTeX 输出。
3. LaTeX 到 PDF （tectonic）：从 LaTeX 输入创建 PDF 文档。

贡献

积极鼓励提出拉取请求、分支和直接复制粘贴！此外，我相对较新 Rust（以及一般编程）所以对任何建议或一般性的建议都非常欢迎。

我发现了一个问题。我应该为 mdbook-latex 或 md2tex 创建一个问题吗？

都可以。 mdbook-latex 可以被视为由 md2tex 完成的 LaTeX 生成的前端。所以如果出现 LaTeX 错误，您可能更喜欢为 md2tex 创建一个问题。否则，为 mdbook-latex 创建问题也是一个不错的选择。但任何问题都是好的问题，所以不要担心它是否在“正确的”存储库中，无论怎样，我都应该能够看到它！

我们稳定了吗？

以下是我在当前正在工作的功能列表（大致按“自上而下”的方向）。

• 添加对方程界限 "( x^2 )" "[ x^2 ]" 的支持。
• 允许 SVG 图片（转换为 PNG 用于 LaTeX）。
  • 配置 resvg 库以将 SVG 转换为 PNG。
  • 将 SVG 保存到 book/latex 目录以保持 src 干净。
• 添加 CI/CD 管道（travis）
• 将所有 LaTeX 数据移动到单个模板文件（src/template.tex）中。
• 添加对原始 HTML 表格的支持。
• 通过 syntect 如同 lumpy-leandoc 添加语法高亮。
• 通过 Rayon 如同 lumpy-leandoc 添加并行转换。
• 使用 lumpy-leandoc 的方法处理事件（将 current 事件替换为 fold）。
• 编译 Rust 书籍 和 mdbook 文档，不出现任何错误或警告（例如缺少 Unicode 字符）。请参阅 Rust 书架状态 了解最新进度。
• 在 "pdf" 功能配置中将 "tectonic" 依赖项。
• 添加 "目录" mdbook toml 选项。
• 添加 "markdown" mdbook toml 选项。
• 添加 "单词数" mdbook toml 选项。
• 添加 "示例" 目录。
• 创建文档并将相关文档移动到 md2tex。
• 添加自定义 LaTeX 头部的选项。
• 添加替代 markdown-to-latex 转换插件选项。
• 添加测试套件。
• 交叉编译二进制文件（trust）
• 添加使用 mdproof 生成 PDF 的选项以跳过 LaTeX 依赖项。
• 完全符合 CommonMark 规范。

另请参阅

以下项目为 mdbook-latex 提供了指导（或者足够酷，值得分享！）

• mdbook-epub：为 mdbook 创建 EPUB 文件的后端。
• mdbook-linkcheck：用于 mdbook 的后端，将验证 URL 链接。
• LaTeX-rs：一个用于程序化 LaTeX 生成的酷库，我希望最终能将其集成。
• crowbook：一个强大的程序，可以从 markdown 代码生成 HTML、PDF 和 EPUB 文件。有一个很棒的 在线演示页面 可以交互式地尝试。在某些方面与 mdbook 类似，但更专注于“小说和虚构”。尽管足够通用，可以处理许多不同的项目。
• no starch press：由正规出版社专业制作的 Rust 编程语言。保证比 mdbook-latex 出现的错误更少！
• lumpy-leandoc：通过 pulldown_cmark 实现 markdown-LaTeX 转换的更优雅的方法，比当前 md2tex 提供的方法更优雅。还包括通过 Rayon 实现并行性和通过 syntect 实现语法高亮！

mdbook-latex 无法构建我的书籍！现在怎么办？ >:(

自动方法

哎呀！这意味着我还有更多工作要做。如果你 绝对需要立即得到你的 PDF，那么最快捷的选项是在你书的在线页面的右上角选择 print 图标。

另一种方法是运行 markdown 文件通过像 pandoc 这样的替代 markdown 到 LaTeX 转换器

pandoc --from markdown --to latex book/latex/MY_BOOK.md -o book/latex/MY_BOOK.pdf

或者运行它通过免费（就像免费停车一样）的在线解决方案

• https://www.markdowntopdf.com/
• https://md2pdf.netlify.com/
• https://dillinger.io/

手动方法

然而，如果你不介意与 LaTeX 打交道，以下是当构建步骤失败时的我的过程

1. 将 book.toml 中的 LaTeX 配置更改为仅输出 LaTeX 和 markdown 文件

[output.latex]
latex = true
pdf = false
markdown = true

2. 首先通过手动运行它并查找 ! LaTeX Error 来查看 tectonic 运行到错误的地方

tectonic book/latex/MY_BOOK.tex

note: this is a BETA release; ask questions and report bugs at https://tectonic.newton.cx/
Running TeX ...
error: something bad happened inside TeX; its output follows:

===============================================================================
(MY_BOOK.tex
.
.
.
! LaTeX Error: Missing \begin{document}.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...

l.260 \clearpage

No pages of output.
Transcript written on MY_BOOK.log.
===============================================================================

error: the TeX engine had an unrecoverable error
caused by: halted on potentially-recoverable error as specified

啊哈！! LaTeX Error: Missing \begin{document}.

ed book/latex/MY_BOOK.tex

tectonic book/latex/MY_BOOK.tex