Kobold

Kobold 是一个具有友好 CLI 的静态站点生成器。

Usage: kobold <COMMAND>

Commands:
  init   Create a new Kobold project in the specified directory
  build  Generate website from the Kobold project at the specified directory
  help   Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

安装

您可以通过 Cargo 安装 Kobold

cargo install kobold-ssg

只要 Cargo 的 bin 目录（默认情况下为 $HOME/.cargo/bin）在您的 PATH 中，您就设置好了。

或者您可以克隆 仓库 然后使用

cargo run --release -- [kobold commands, options]

快速开始

创建一个新的 Kobold 项目

kobold init koboldsite.com

这将创建 koboldsite.com/ 目录并将其初始化为 git 仓库，具有 Kobold 所需的目录结构

koboldsite.com/
├── content/
│   └── index.md
├── layouts/
│   └── default.html
├── macros/
│   └── ...
└── css/
    └── ...

项目可以包含更多具有其他名称的子目录，但子目录 site/ 和 site.old/ 是为 Kobold 保留的。

如果您使用过任何其他静态站点生成器，您可以根据这个目录结构推测出 Kobold 的工作方式。

index.md 文件是网站的主页，以下是其内容

---
title: Home page
---

# Hello Kobold!

您已经可以生成网站

kobold build koboldsite.com

该命令在 koboldsite.com/ 目录中创建一个 site/ 子目录，其中包含生成的网站。您可以使用您最喜欢的网络浏览器访问网站

firefox koboldsite.com/site/index.html

或启动 HTTP 服务器，例如

cd koboldsite.com/site && python -m http.server

然后您可以通过在 content/ 下添加更多文件来在网站上工作。

具有 .md 扩展名的文件会被处理以

1. 评估 宏（如果有的话）
2. 将 Markdown 转换为 HTML
3. 应用所需的页面布局（默认情况下为 default.html）

所有其他在 content/ 下的文件都会以相同的目录结构原样复制到 site/ 中。目录 css/ 也会原样复制到 site/ 中。

可以将自定义页面布局添加到 layouts 目录中：它们是 Tera 模板，并且必须具有 .html 扩展名。布局中的占位符，如 {{title}} 和 {{body}}，在网站生成过程中会被适当的值替换（见 上下文变量）。

要选择自定义页面布局，请在页面的 frontmatter 中添加 layout: filename（省略 .html 扩展名）。

页面 frontmatter

Markdown 内容页面（即在 content/ 目录中具有 .md 扩展名的文本文件）可以以 YAML frontmatter 开头。这是两个仅包含 --- 的行之间的 YAML 片段。如果存在，它将包含用于告知页面处理的元数据。

以下 frontmatter 中的键对 Kobold 有特殊意义

• title：页面标题
• layout：用于此页面的布局。为了使用布局 blog_post.html，请使用 layout: blog_post（省略扩展名）
• tags：一个标签数组，将被附加到此页面上，例如 [c++, war-stories]

其他任何键都将在网站生成过程中作为 上下文变量 提供。

使用宏生成内容

Tera 宏 可以用于自动化页面内容的生成。在 Kobold 项目中，它们位于 macros/ 目录中的文件（不允许有子目录）并可以具有任何扩展名（例如 .md、.html 或 .tera）。

从 Markdown 内容页面使用

宏是唯一可以在内容页面中使用的 Tera 功能。它们自动在 macros 命名空间下提供（无需 {% import %}），并且可以调用如下

{{ macros::macroname(parameter="value") }}

请记住，Tera 宏需要使用关键字参数。宏调用在 Markdown 转换为 HTML 之前会被其评估的输出替换。

从布局中使用

与 Markdown 内容页面不同，布局是完整的 Tera 模板，因此宏的工作方式与 Tera 中的通常方式相同（它们不会自动导入）

{% import '../macros/mymacrofile.html' as somemacros %}

{{ somemacros::macroname(parameter="value") }}

对于布局和内容页面，可以将 上下文变量 作为参数传递给宏。

Tera 上下文变量

以下变量在 layouts/ 目录中的模板以及 在 Markdown 内容页面中评估宏 时都可用

• 标题：YAML 前置部分中声明的页面标题
• 路径：相对于网站根目录的页面 URL /
• 标签：附加到页面的标签
• 数据：一个包含在页面前置部分设置的任何额外变量的映射
• pages：一个包含所有对应信息 所有 内容页的 Page{title, path, tags, layout, data} 的数组
• body（仅在布局中，不在内容页面中）：页面主体，宏已评估并转换为 HTML

路线图

• 尽可能使用规范性而不是描述性的用户友好错误消息
• 支持通过 Tera 宏 以编程方式生成页面内容
• 自动对代码块进行语法高亮显示
• 为 fish shell 提供良好的自动补全
• 使通过前置部分中的 needs 键选择的页面主体作为 Tera 上下文的一部分提供

为什么？

我想拥有一个个人网站，并想练习我的 Rust。

相关工作

Kobold 是从头开始编写的，但它与更成熟的 Zola 和 Cobalt 有很多相似之处。Kobold 缺少它们的一些功能，但作为交换，它试图变得非常容易使用，以至于你可以在不阅读任何文档的情况下开始使用 kobold 命令来创建网站。

我也欣赏 Hugo 的关注速度和其无废话的工作流程，以及简码非常有意义，因此 Kobold 的宏试图复制其中的一些有用性。

不是专门的静态网站生成器，但 Sylvain Kerkour 的 使用 100 行 Rust 构建 static site generator 是我入门的一个很好的资源。

贡献

如果你尝试使用 Kobold，任何反馈都备受欢迎。

以问题或补丁形式进行的贡献更为赞赏。