文档格式化工具

这是一个使用模板和数据格式化文档的工具。可以合并多个数据文件。路径和文件可以在模板中进行包含和引用。

数据和输入文件被传递给模板引擎 Handlebars。

模板

模板文件可以是 Handlebars 支持的任何格式。使用的实现是 handlebars-rust。没有启用 rust-embed 功能。

Handlebars 是一个功能丰富的模板引擎。它支持广泛的特性。Handlebars 的文档非常详尽，可以在 这里 找到。

用法

docfmt [OPTIONS] <TEMPLATE> <OUTPUT>

选项

-c, --config

包含配置的 TOML 文件的路径。配置文件可以用来定义模板、输出、数据和包含项。命令行参数优先于配置文件。

-i, --include

包含在文档中的路径或文件。可以使用多次。目录会递归遍历。文件和目录会从路径和文件扩展名中移除。在遍历目录时忽略点文件。文件会按照定义的顺序包含。

在 Windows 上，用于命名模板的移除路径会被转换成使用正斜杠。

-e, --ext

要包含在目录中的文件扩展名的逗号分隔列表。默认为 md,markdown。

-d, --data

包含在文档中的路径或文件。可以使用多次。目录会递归遍历。数据可以定义为 JSON 或 TOML 格式。类型由文件扩展名确定。如果定义多次，数据会被合并。合并会按照文件定义的顺序进行。最后一个文件会覆盖前面的文件。

-f，--force

如果输出文件已存在，则覆盖它。

-v，--verbose

启用详细日志记录。如果定义为日志级别，则在程序以调试模式编译时设置为debug，否则设置为info。如果没有定义，则日志级别设置为warn。日志将写入stderr。

-s，--strict

限制访问模板中不存在的字段或索引。如果定义为程序将退出错误，如果访问了不存在字段或索引。如果没有定义为程序将忽略此类访问。

--follow

在遍历目录时跟随符号链接。此选项仅在Unix系统上可用。

-V，--version

打印版本信息。

-h，--help

打印帮助信息。

参数

<TEMPLATE>

模板文件的路径。模板文件可以是Handlebars支持的任何格式。如果模板在配置文件中定义，则可以省略模板文件。

<OUTPUT>

输出文件的路径。如果输出在配置文件中定义，则可以省略输出文件。

配置

配置文件是一个TOML文件。以下键是受支持的

template = "<path to template>"
output = "<path to output>"
force = false
follow = false
verbose = false
strict = false
include = ["<file to include>", "<path to include>"]
ext = ["md", "markdown"]
datafiles = ["<path to json-file>", "<path to toml-file>"]

[data]
title = "My title"

template和output键是必需的。force、follow、verbose和strict键是可选的，默认为false。include和ext键是可选的，默认分别为[]和[""md"", ""markdown""]。datafiles键是可选的，默认为[]。data键是可选的，默认为{}。