Lib.rs

› 模板引擎 | 命令行工具
#网站 #ssg #静态网站

程序 rssg

一个利用 shell 命令的 Rust 静态网站生成器

由 Kyllingene 所有。

8 个稳定版本

1.8.0 2023年11月15日
1.7.3 2023年9月17日
1.7.2 2023年3月30日

38 在 模板引擎 中

25 每月下载量

MIT 许可证

56KB
1.5K SLoC

RSSG

一个 Rust 静态网站生成器

内容

使用

一个示例网站可以在 example-site 目录中找到。

使用 rssg -i path-to-new-site 创建新网站。

命令行使用

rssg [options]
     -h |    --help : print this help dialog
     -c | --compile : compile the site
     -i |    --init : create a new site
     -v | --verbose : include debug output
     -f |   --force : force recompilation
                      rebuilds cache
          --content : set source directory
                      defaults to `content`
           --output : set output directory
                      defaults to `output`
           --public : set public directory
                      defaults to `public`
            --clean : cleans the `output`
                      and `temp` directories

文件结构

网站使用结构来简化编译。结构看起来像这样

my_site/
├── content/
│   └── ...
├── templates/
│   └── ...
├── public/
│   └── ...
├── output/
│   └── ...
└── rules.toml

所有你的页面都放在 content 目录中。这些文件将由 rules.toml (关于它的更多信息见下文) 处理，它可能会在 templates 目录中的模板中运行它们。结果被放置在 output 目录中。任何在 public 目录中的文件都将无修改地复制到输出中，保留目录结构。

rules.toml

生成器的核心是 rules.toml。它决定了 content 目录中的所有内容会发生什么。它由两部分组成：过滤器和规则。

过滤器

过滤器接收一个输入文件，运行一个命令（可能是为了更改文件），并输出一个文件。一个命令可能看起来像 pandoc {full} -o {outfile}。在这个例子中，进行了两个替换：首先，{full} 被替换为输入文件的完整路径；其次，{outfile} 被替换为过滤器的输出文件。替换后，它可能看起来像这样：pandoc content/index.md -o temp/<hash>/index.html。

所有过滤器都需要一个输出文件。这个文件会被替换，然后在命令中替换为 {outfile}。有效的替换如下所示

  • {full}：输入文件的完整路径。
  • {dir}：输入文件的上层目录。
  • {name}：输入文件的文件名（不含扩展名）。
  • {ext}：输入文件的扩展名。

在 rules.toml 中，过滤器可以位于文件顶层的一个列表中。以下是一个例子，该例子运行文件通过 pandoc，然后输出时不更改其路径（但更新扩展名）

[[filters]]
# The name of the filter, to use in rules
name = "markdown"

# The command to run, with substitutions
# example/path.html -> `pandoc example/path.html -o temp/<..>/path.html`
command = "pandoc {full} -o {outfile}"

# The resulting file, with substitutions
# !!! NOT neccessarily where the file will be in the final output
# example/path.html -> <hash of command + filepath>/path.html
outfile = "{dir}/{name}.html"

您也可以在规则规范（见下文）内部指定“内联”过滤器，如下所示

# ...
filters = [
    {command = "pandoc {full} -o {outfile}", outfile = "{dir}/{name}.html"}
]
# ...

注意：过滤器输出文件在生成过程中存储在 temp 目录中，具有唯一的目录名称。这对于网站开发是不相关的。

过滤器也可以省略 outfile 属性。这样的过滤器不会输出任何信息；对于其他过滤器来说，它们似乎从未存在过。这样的过滤器可以直接修改前一个过滤器的输出，但这是不建议的。这些过滤器用于像日志记录和生成网站地图这样的东西。

默认情况下，过滤器永远不会看到原始源文件。即使是第一层过滤器也只看到 YAML-过滤后的版本。然而，如果您有一个没有 outfile 的过滤器，您可以通过指定 give_original = true 来获取未更改的源文件路径。 永远不要 用这个来修改源文件，除非您有特殊的原因。

模板

模板是您可以用来封装其他文件的文件。例如，您可能有一个 default.html 模板，其中包含标题和页脚，以将页面内容包裹在其中。它们位于 templates 目录中，并有自己的替换规则

  • {{data}}：嵌入页面的完整数据。
  • {{version}}：编译页面所使用的 rssg 版本。
  • {{data.<key>}}：内容文件的前置数据。

请注意，与命令替换不同，这些用双括号括起来。内容文件可以具有 YAML 前置数据，用于这些替换。例如，您可能在每个页面中都有一个 title 键，以及在模板中使用该键的 title 元素。前置数据由三横线（---）包围，并且 必须 在开始处。以下是一个例子（假设一个基本的 markdown-to-html 过滤器）

input.md

---
title: Homepage
---

# Hello, World!

template.html

<html>
    <head>
        <title>{{data.title}}</title>
    </head>
    <body>
        {{data}}
    </body>
</html>

output.html

<html>
    <head>
        <title>Homepage</title>
    </head>
    <body>
        <h1>Hello, World!</h1>
    </body>
</html>

规则

过滤器本身没有任何作用；它们必须在规则内部使用。规则由四个组件组成：正则表达式模式（rule）、过滤器列表（filters）、模板列表（templates）和输出（output）。当它们应用于文件时，首先按顺序将每个过滤器应用于文件。然后按顺序将每个模板应用于文件。结果存储在输出路径，以output为前缀。一旦一个规则匹配了一个文件，就没有其他规则可以匹配。

注意：与过滤器不同，规则直接在输出目录中存储其输出文件。

此规则匹配所有以.md或.markdown结尾的文件，将它们转换为HTML，应用一个模板，然后将其保存到一个以它的名字命名的目录中，但文件名为index.html（这将urlexample.com/contact.html转换为example.com/contact/）

[[rules]]
# starts with any characters, ends in .md or .markdown
rule = ".*\\.(md|markdown)"

# Can also use inline filters, see [filters](#filters)
filters = ["markdown"]

# -> templates/default.html
templates = ["default.html"]

# example/path.html -> output/example/path/index.html
output = "{dir}/{name}/index.html"

规则，就像过滤器一样，可以省略output属性。在这种情况下，不会应用任何模板，也不会创建任何文件或目录。对于规则和过滤器，同样的警告也适用；您真的不应该在无输出的规则内部更改数据。

这些都是推荐的风格指南。创建名为rules或filters的TOML列表的任何其他方式都可以工作。这只是最干净的方式。如果您需要出于任何原因进行更改，请查看官方TOML网站。

预命令和后命令

在您的rules.toml中，您可以在构建网站之前和之后添加任意命令。您可以在根级别的pre_commands列表中列出预命令，并在post_commands列表中列出后命令。预命令和后命令都不会进行任何替换，它们按原样运行，如果退出码非零，会导致构建失败。

贡献

首先，感谢您考虑为项目做出贡献！

目前有几件事需要改进。首先，单元测试应该真正创建。其他一些小的更改也很受欢迎；开发时的监视模式（监视文件，当有东西改变时重新编译），更可配置的日志系统，更好的日志记录，文档和整体风格改进。这个readme是整个项目的缩影；功能性强，但存在缺陷。

无论您做什么，首先都要进行测试！ 使用提供的示例（或您自己的）来确保正确性。如果您添加了一个功能，请为其添加一个测试。

在提交任何拉取请求之前，请运行cargo clippy和cargo fmt。这些不仅有助于解决风格和性能问题，而且clippy还可以意外地捕获您代码中的一些坏错误。然而，只要您的贡献是有益的并且功能性的，我就不会对格式过于挑剔。

除非您明确表示，否则所有贡献都受项目许可证（MIT）的约束。

永远不要提交不完整的代码（todo!()、unimplemented!()等）。

版权（c）2023 Kyllingene，MIT许可证。

依赖项

~6.5–8.5MB
~157K SLoC