3 个版本

0.1.2	2022年10月17日
0.1.1	2022年10月15日
0.1.0	2022年10月14日

#2091 in 命令行工具

30 个月下载量

MIT 许可证

42KB
644 行

`mksite`

不依赖文件格式的静态网站生成器

安装

如果您已经安装了 Rust 和 Cargo

cargo install mksite

或者，您可以通过 git 安装

cargo install --git https://github.com/alterae/mksite

用法

mksite <COMMAND>

Commands:
  build  Build the site according to `mksite.toml`
  clean  Delete all build outputs
  init   Initialize a `mksite.toml` file in the current directory
  new    Scaffold an empty site in a new directory
  help   Print this message or the help of the given subcommand(s)

Options:
  -q, --quiet                  Do not print log messages
      --log-level <LOG_LEVEL>  What level of logging to enable (error, warn, info, debug, or trace) [default: info]
  -h, --help     Print help information
  -V, --version  Print version information

mksite 是一个程序，用于将文本文件树转换为不同的文本文件树，通常是一个网站。一个典型的 mksite 项目的结构如下：

mksite.toml — mksite.toml 文件是项目的核心，定义了其他重要目录的名称、模板可用的数据以及对文件应用转换。
layout/ (可选) — layout/ 目录包含布局，例如 html 模板，在文件转换后应用。如果您不需要任何布局，或者不希望使用 mksite 的布局系统，可以安全地省略此文件夹。在 mksite.toml 中可以自定义 layout/ 目录的名称。
out/ (生成) — out/ 目录在构建网站时由 mksite 生成，包含 src/ 目录的转换内容以及 static/ 目录的内容，直接复制。在 mksite.toml 中可以自定义 out/ 目录的名称。
src/ — src/ 目录包含网站的所有非静态源文件。在 src 中的文件必须是有效的 UTF-8，并且可以使用 Tera 模板语言包含模板表达式。除此之外，它们可以是任何东西：LaTex、HTML、Markdown、您自己的自定义标记语言，或者完全不同的事物。可以在 mksite.toml 中自定义 src/ 目录的名称。
static/ (可选) — static/ 目录包含静态文件，如样式表或图片，它们将被直接复制到 out/ 目录。不会发生模板化或转换。可以在 mksite.toml 中自定义 static/ 目录的名称。

配置

一个示例 mksite.toml 文件如下所示

dirs.src = "src"
dirs.out = "out"
dirs.static = "static"
dirs.layout = "layout"

[data]
author = { name = "Jane Doe", email = "[email protected]" }
copyright = 2022

[transforms]
md.html = "pandoc -f markdown -t html"
scd.html = ["scdoc", "pandoc -f man -t html"]

前四行告诉 mksite 分别是 src/、out/、static/ 和 layout/ 目录的名称。更改这些将改变 mksite 读取和写入数据的位置。例如，dirs.out = "www" 将导致 mksite 在名为 www/ 的文件夹中写入构建输出。

接下来是 data 部分，您可以在其中定义任意数据，这些数据将被传递到模板渲染中。在模板中，这些数据将在 data 变量下提供。有关模板语法的详细信息，请参阅 Tera 文档。

最后，我们有 transforms 部分。转换是指接收标准输入上的字节数据流，并返回标准输出上的字节数据流的命令或命令链。转换可用于实现 mksite 本身不支持的许多功能，例如 markdown 渲染和语法高亮。转换定义的基本语法是 in.out = "command" 或 in.out = ["command1", "command2", ...]，其中 in 是转换操作处理的文件扩展名，out 是转换生成的文件扩展名，command 是将页面通过管道的命令。有关转换的详细信息，请参阅以下内容。

此配置文件中的所有字段都是可选的。

布局

布局只是位于 layout/ 目录中的 Tera 模板，它们接受一个额外的 page.content 变量。布局必须是有效的 UTF-8，但除此之外，它们可以是任何格式。

一个示例布局文件如下所示。

<!-- layout/_.html -->
<!DOCTYPE html>
<html>
  <head></head>
  <body>
    <!-- The "| safe" prevents Tera from html-escaping the content. -->
    {{ page.content | safe }}
  </body>
</html>

有两种类型的布局：默认布局和覆盖布局

覆盖布局与 out/ 目录中的特定文件的名称、扩展名和相对路径相同，并且仅适用于该文件。例如，布局 layout/blog/index.html 将仅适用于页面 out/blog/index.html。

默认布局的名称为 _.ext，其中 ext 是某种文件扩展名。默认布局应用于相应目录中的所有文件以及没有默认布局的嵌套目录中的所有文件。例如

layout/
    _.html
    blog/
        _.html
        index.html

在这个例子中，layout/blog/_.html 将应用于 out/ 中的所有 html 文件，除了 index.html，而 layout/_.html 将应用于 out/ 中的所有 html 文件，除了 blog 目录的内容。

注意布局是在变换之后根据变换输出的文件扩展名应用的。因此，像 _.html 这样的布局将应用于所有生成的 html 文件，无论这些 html 文件是手动编写的还是通过变换从 markdown 或其他内容生成的。

如果没有找到适用于文件的布局，或者没有找到 layout/，则不会应用任何布局。

如果存在适用的布局，但您希望防止它应用于文件或文件夹，可以定义一个“空”布局，如下所示

{{ page.content | safe }}

变换

变换具有 输入扩展名、输出扩展名 和一个命令或 命令链。

src/ 目录中每个与变换输入扩展名匹配的页面的文件被作为字节数据流传入变换，生成的字节数据流被写入 out/ 目录中的文件，文件名和路径与输入相同，文件扩展名与变换的输出扩展名匹配。每个页面可以传入多个变换，并且多个变换可以输出相同格式。输入和输出的关系是多对多。

警告重要的是要注意，变换的输入和输出是 任意字节数据流，不一定是有效的 UTF-8 字符串。这对于与外部非 Rust 工具接口很重要，但也有一些注意事项

尽管这可能在将来发生变化，但到目前为止，所有模板和布局都必须是有效的 UTF-8。这意味着变换可以输入和输出任意字节数据，但变换的原始输入（src/ 目录中的文件）将是 UTF-8。此外，不支持非 UTF-8 文件的布局，尝试为 .pdf 文件定义布局将导致错误。

如果变换有一个单个命令，页面将被传入该命令，并将命令的输出写入输出文件。例如，这些变换

[transforms]
md.html = "pandoc -f markdown"
md.pdf = "pandoc -f markdown -t pdf"

将使用 pandoc 为 src/ 中的每个 markdown 文件生成 out/ 中的 html 文件和 pdf 文档。

如果变换有一个命令链，页面将按顺序传入命令链中的每个命令，并将最后一个命令的输出写入输出文件，就像在 shell 管道中一样。例如

[transforms]
scd.html = ["scdoc", "pandoc -f man"]

将使用 scdoc 从每个 .scd 文件生成 man 页面，并将其立即通过 pandoc 转换为 html。

贡献

欢迎拉取请求和问题报告，但请在提交 PR 之前运行 cargo fmt。

示例

请参阅 docs/ 文件夹，了解使用 mksite 构建网站的示例。

许可

mksite 采用 MIT 许可协议。

依赖项

~8–21MB
~235K SLoC