mdbook-tectonic

• Rust Bookshelf状态
• 安装
• 卸载
• 主要依赖
• 它是如何工作的？
• 贡献
  • 我发现了一个问题。我应该为mdbook-tectonic或md2tex创建一个问题吗？
• 我们稳定了吗？
  • 手动方法
  • 最后

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

Rust Bookshelf状态

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

安装

需求

• Rust
• mdbook
• Tectonic + 支持库

Cargo安装 + 配置

cargo install mdbook-tectonic

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

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

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

卸载

要卸载mdbook-tectonic，请在shell中输入以下内容

cargo uninstall mdbook-tectonic

然后删除[output.latex]配置中的book.toml

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

主要依赖

mdbook-tectonic建立在一些真正出色的项目之上，包括

• pulldown-cmark：解析Markdown源AST。
• Tectonic：从转换后的LaTeX代码创建最终的PDF文件。
• md2tex：将Markdown源代码转换为LaTeX。这是md2pdf的一个分支，一个将Markdown代码转换为LaTeX和PDF的出色实用工具。我希望最终能够将一些更新反馈回主分支。md2tex和mdbook-tectonic是同时开发的，但它们是独立的程序。因此，如果想要使用替代的Markdown到TeX转换器，应该能够轻松地将它集成到mdbook-tectonic中。

它是如何工作的？

总的来说，从mdbook源代码到PDF输出的过程分为三个步骤，或称为“转换”。

1. mdbook源代码到JSON组织化的Markdown (mdbook-tectonic)：从mdbook检索JSON格式的数据。调用md2tex和tectonic分别用于生成LaTeX和PDF。
2. Markdown到LaTeX (md2tex)：将Markdown输入转换为LaTeX输出。
3. LaTeX到PDF (tectonic)：从LaTeX输入创建PDF文档。

贡献

积极鼓励提交拉取请求、创建分支和直接复制粘贴！另外，我对Rust（以及编程总体上）相对较新，因此任何建议或一般性建议都总是受欢迎的。

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

两者都可以。可以将mdbook-tectonic视为由md2tex生成的LaTeX生成的前端。因此，如果LaTeX出现错误，可能更倾向于在md2tex中创建问题。否则，创建与mdbook-tectonic相关的问题是个不错的选择。但任何问题都是好问题，所以不必担心是否在“正确”的仓库中，无论如何，我应该都能看到它！

我们稳定了吗？

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

• 添加对方程界定符“( 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的方法处理事件（用fold替换current事件）。
• 编译The Rust Book和mdbook文档，没有任何错误或警告（例如缺少Unicode字符）。请参阅Rust Bookshelf状态以获取最新进度。
• 将“tectonic”依赖项放入“pdf”功能配置。
• 添加“目录”mdbook toml选项。
• 添加“markdown”mdbook toml选项。
• 添加“单词数”mdbook toml选项。
• 添加“示例”目录。
• 创建文档并将相关文档移至md2tex。
• 添加自定义LaTeX头部的选项。
• 添加替代Markdown到LaTeX转换器插件选项。
• 添加测试套件。
• 交叉编译二进制文件（trust）
• 添加使用mdproof生成PDF的选项以跳过LaTeX依赖项。
• 完全符合CommonMark规范。

手动方法

如果您不介意手动处理LaTeX，以下是我在构建步骤失败时的处理过程

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

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

2. 首先手动运行tectonic，查找错误并寻找! LaTeX Error

tectonic book/latex/MY_BOOK.tex

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

在这个例子中，mdbook-tectonic未能输出非常重要的\begin{document}行。

3. 在您喜欢的编辑器中修复这个严重的错误，并重新运行tectonic（重复此步骤，直到tectonic成功编译PDF）

ed book/latex/MY_BOOK.tex

tectonic book/latex/MY_BOOK.tex

这是一个优雅的方法吗？不是。它有效吗？有时候。它痛苦吗？总是。

最后

如果您特别有冒险精神，可以创建一个issue或联系我（[email protected]），以防止未来发生相同的错误。我很乐意与您合作，以确保您的文档能够成功编译！

: ^ )