rsmooth

围绕 pandoc 的意见包装器，用于将 Markdown 文件 转换为 PDF，办公文档（odt，docx）和幻灯片。rsmooth 的主要思想是在 Front Matter 中定义所有所需信息（Markdown 文档中的 YAML 头部），因此不需要外部配置。

为了提供更大的灵活性，可以通过 Terra（与 Jinja2 非常相似的模板语言）运行输入文件的内容。这允许您调整 pandoc 输入的内容。目前，rsmooth 可以将 Markdown 文件转换为 PDF，OpenDocument Text（.odt），Office Open XML Document（.docx）和幻灯片，使用 Reveal.js。除了使用 pandoc 的默认 PDF 创建机制外，还可以使用 LibreOffice。

安装

Cargo

如果您已安装 cargo，只需调用

cargo install rsmooth

二进制文件

您可以在 发布部分 下载二进制文件。目前仅提供 Linux x86_64 的二进制文件（其他版本很快就会提供）。

用法

本节将概述最常用的工作流程和选项。使用 rsmooth 的 --help 标志将显示所有可用功能。

PDF 导出

以这个简单的文件为例（example.md）

---
title: A Sample Document
author: John Doe
template: ~/templates/document.tex
---

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor.

要基于此文件创建 PDF，请调用

rsmooth example.md

这将创建一个example.pdf文件。如果您想指定PDF的另一个名称，请使用-o标志。结果文档的外观由YAML头中的template字段指定的pandoc模板定义。模板文件的路径可以是相对路径或绝对路径；rsmooth还支持环境变量（如$HOME）和波浪号作为家目录的缩写（shell扩展）。

导出到其他格式

如上所述，rsmooth还支持创建odt、docx文档和reveal.js幻灯片。可以通过设置--format（或-f）标志为以下值之一来调整此功能

• PDF --format pdf输出一个PDF文件。您可以通过在文档头中设置engine来更改使用的引擎（提示：当前默认为xelatex）。
• ODT --format odt将文档输出为OpenDocument Text（通常称为odt）办公文档。您可以通过在文档头中设置reference来更改文档的外观。（注意：当前在导出到odt时忽略template字段）。
• DOCX --format docx将文档保存为Office Open XML Document（即docx）。您可以通过在文档头中设置reference来更改文档的外观。
• ODT & PDF --format odtpdf首先将您的文档导出为odt文件，然后使用您的LibreOffice安装将其转换为PDF。与其他基于办公文档的工作流程一样，您可以使用reference字段来更改结果的外观。
• Reveal.js --format reveal使用reveal.js，rsmooth可以将您的文档导出为幻灯片。不要忘记使用文档头中的revealjs-url字段指定reveal.js资源的路径。

在输入文件上应用Tera模板引擎

Pandoc的模板功能提供了许多灵活性来控制输出。但有时需要更多控制输入端。这就是为什么rsmooth允许您使用Terra模板引擎来更改markdown输入。您可以通过设置do_tera和tera_context以及传递额外的数据（请阅读相应字段的文档以获取更多信息）来启用Tera。您可以在他们的文档中了解更多关于Tera的使用方法。简例

main.md

---
title: Tera Example
do_tera: True
tera_context: 
	foo: Fnord
	shopping:
		- name: Eggs
		  amount: 6
		- name: Bread
		  amount: 2
		- name: Milk
		  amount: 1
---

# Notes

The content of the context variable `foo` is »{{ foo }}«. My shopping List:

{% for item in shopping %}
- {{ item.amount}}x {{ item.name }}
{% endfor %}

{% include "section.md" %}

section.md

# A Section

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla a commodo urna.
Aliquam elementum molestie tempor. Suspendisse potenti. Class aptent taciti
sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Etiam
sed ornare ipsum, in condimentum velit.

调用rsmooth main.md将产生以下pdf

示例文件

应用程序可以创建一个展示rsmooth一些功能的示例markdown文件。

rsmooth example-file -o example.md

将内容保存到example.md文件中。不使用-o标志时，将示例文件输出到STDOUT。

可用的文档选项

通过使用YAML头部（前文），您可以更改rsmooth的行为并使用其他功能。

注意：YAML头部的全部内容也将对pandoc可用，因此可以使用以下语法在模板文件中使用它：$VAR_NAME$。

关于路径的一些说明

Rsmooth会尝试解析配置头部中使用的各种路径。由于它们将被shell展开，因此您可以使用环境变量和波浪号（~）来表示您的家目录。相对路径将以输入文件的位置为基准进行处理。注意：只有下面文档化的字段支持此路径解析机制。

模板

字段名称： template

描述： 模板文件的路径。更多关于这些文件的信息，请参阅pandoc文档。如果没有提供模板，则将使用pandoc的默认模板。当前在导出文档为odt或docx时，模板字段将被忽略。

类型： 字符串（路径）。

默认值： 无。

参考文件

字段名称： reference

描述： ODT或docx文件的路径，作为样式参考。更多关于此选项和其用法的信息，请参阅特定写入器选项。

类型： 字符串（路径）。

默认值： 无。

PDF引擎

字段名称： engine

描述： 用于创建PDF文档的LaTeX引擎名称。这将在内部设置pandoc的--pdf-engine选项。

类型： 字符串。

默认值： xelatex（因为我正在使用它）。

Pandoc选项

字段名称： pandoc_options

描述： 将附加选项传递给pandoc调用。多个参数表示为字符串列表。

类型： 字符串/字符串列表。

默认值： 无。

将输入应用于Tera

字段名称： do_tera

描述： 确定Markdown输入是否应通过Terra模板引擎传递。这使您可以对输入有更多的灵活性，这是通过调整pandoc模板文件无法实现的。特别适用于将文档内容拆分为多个Markdown文件，并使用Tera的{% include "section_01.md" %}语法包含它们。您可以使用Tera上下文字段将信息传递给Tera。您可以在其文档中了解更多关于Tera语法的知识。

类型： 布尔值（true/false）。

默认值： False。

Tera上下文

字段名称： tera_context

描述: 有时向 Tera 引擎（上下文）传递一些额外的信息可能很有用。这可以通过为此字段提供一个字符串到任何 YAML 支持的类型（字典）的映射（dict）来实现。有关 YAML 中映射的更多信息，请参阅这里。

类型: 字符串到任何类型的映射。

默认值： 无。

参考书目文件

字段名称: bibliography

描述: 包含用于您文档中引用的参考书目元数据的文件路径。Pandoc 支持 BibLaTeX、BibTeX、CSL JSON 和 CSL YAML 文件。有关如何使用此功能的信息，请参阅 Pandoc 文档。注意：为了使用 Pandoc 的引用功能，您的系统上必须安装 pandoc-citeproc。

类型： 字符串（路径）。

默认值： 无。

引用样式

字段名称: csl

描述: 描述文档中引用样式的 引用样式文件 的路径。

类型： 字符串（路径）。

默认值: 无（Pandoc 将使用芝加哥手册作者-日期格式）。

环境变量

rsmooth 假设 Pandoc 可执行文件可以通过 pandoc 命令调用。您可以使用环境变量 PANDOC_CMD 来更改此设置。

LibreOffice 的默认位置是 soffice，并且可以使用 LIBREOFFICE_CMD 环境变量进行更改。