中文README

苏氏

苏氏是一个简单但可定制的静态站点生成器/博客生成器，用 Rust 编写。

安装

使用 Cargo 安装（推荐）

cargo install sushi-gen

ssushi 将被安装到 .cargo/bin。现在检查安装。

ssushi --help

从源码手动编译

克隆此仓库并 cd 进入

git clone https://github.com/fpg2012/sushi
cd sushi

使用 Cargo 构建它

cargo build --release

二进制可执行文件 ssushi 将放置在 target/release

快速开始

对于 Linux 用户

1. 安装 sushi

2. 获取一个启动器（或称为“主题”），例如

   git clone https://github.com/fpg2012/sushi-theme-letter
   

   将启动器复制到配置目录并重命名为 default。在 Linux 上，它是 $XDG_CONFIG_DIR/sushi-gen 或 $HOME/.config/sushi-gen。（参考 directories 中的 ProjectDirs）。不要忘记安装启动器的所有依赖项。

3. 初始化您的网站

   ssushi init [your_site_name]
   

4. 构建网站

   ssushi build
   

5. 现在网站已生成到 _gen 文件夹。您可以使用 sfz 来提供网站服务。

   cargo install sfz
   sfz -r _gen
   

苏氏是如何工作的？

网站结构

一个苏氏网站可能看起来像这样

sushi-theme-letter
├── assets
├── _converters (*)
│   ├── convert.sh
│   └── pandoc-katex
├── _gen
├── _includes (*)
│   ├── footer.liquid
│   ├── header.liquid
│   └── katexcss.liquid
├── index.md
├── notes
├── posts
│   ├── 2021-04-04-some-post-with-assets
│   │   ├── pic1.png
│   │   ├── pic2.png
│   │   └── index.md
│   └── 2022-03-18-some-post.md
├── _site.yml (*)
└── _templates (*)
    ├── page.liquid
    └── post.liquid

实际上只需要 _converters、_includes、_templates 和 _site.yml 这几个文件和文件夹，并且不应该重命名。一旦 sushi 启动，它首先读取这些文件和文件夹并将它们加载到内存中。

模板（使用Liquid模板语言编写）和部分（也是Liquid）应分别存储在 _templates 和 _includes 中。网站配置以 _site.yml 的形式编写。_converters 存储将页面文件转换为HTML页面的可执行文件（即Markdown解析器）。

请注意，Sushi不会直接解析Markdown（或其他格式），它所做的只是编译您提供的模板，并将转换后的页面内容插入其中。您可以编写自己的解析器，或者编写简单的脚本以执行某些解析器（例如 pandoc）。

在读取这些重要配置后，Sushi将执行转换器以找到所有页面。以 . 或 _ 开头的文件夹和文件将被忽略。所有未被识别为“页面文件”的文件将直接复制到相应的位置。

生成的网站存放在 _gen 文件夹中。

网站配置

_site.yml 可能如下所示

site_name: "my site"
author: "my name"
url: "https://example.com"
# ...
convert_ext: ["html", "md"]
converter_choice:
  - md: "converter.sh"
taxonomies: ["category", "tag"]

页面Front Matter

Front Matter包含页面的配置。

---
layout: post
title: "Test of Sushi"
date: "2022-03-12"
tag: ["a", "b", "c"]
category: ["dev"]
---

编写模板

Liquid

Sushi使用Liquid模板语言的Rust实现。有关Liquid语法的详细信息，请参阅Liquid语言和Liquid crate的文档。

全局对象

Sushi提供一些全局Liquid变量。

除了在 _config.yml 和Front Matter中由用户定义的键值对之外，site 和 page 对象还包含一些生成信息。

page.search_text 用于实现搜索功能

sitetree 对象

taxo 对象

模板前端内容

支持模板继承，类似于 Jekyll。如果模板 post 继承模板 page，则 post 的渲染结果将是插入到 page 中的 content。

page_content =="post"=> result1
result1 =="page"=> result2 // the final result in this example

添加部分

如果代码片段被多个模板使用，建议将其拆分到一个部分文件中。所有部分文件都应放在 _includes 文件夹中。

例如，如果 header.liquid 放在 _includes 文件夹中，你可以在模板中使用 {{ include header }} 来包含它。

分页器

分页器用于将页面分割成多个页面（例如，在主页上显示超长的页面标题列表时）。

分页器的使用稍微复杂一些。

首先，sushi 的分页器基于 "list"，它将列表分割成多个 "批次"。因此，您应该将您想要分割的列表放在 page 前端内容中。

---
#...
paginate: sitetree.posts._list # the list you want to split
paginate_batches: 4 # the number of item in a batch
---

然后，在您的 模板 中使用 paginator 对象。例如

{% for page_id in paginator.current_batch %}
  <li><a href="{{ id_to_page[page_id].url }}">{{ id_to_page[page_id].title }}</a></li>
{% endfor %}
{% if paginator.batch_num > 1 %} <!--more than one page-->
{% if paginator.next_batch_num %}
  <a href="{{ paginator.batch_urls[paginator.next_batch_num] }}">{{ paginator.next_batch_num }}</a>
{% endif %}
{% if pageinator.last_batch_num %}
  <a href="{{ paginator.batch_urls[paginator.last_batch_num] }}">{{ paginator.last_batch_num }}</a>
{% endif %}
{% endif %}

分页后，页面 test.md 可能会被分割成

test.html
test
├─1.html
├─2.html
├─ ....
└─10.html

编写转换器

编写转换器相当简单。转换器是一个可执行的程序，它从 stdin 读取输入并将输出写入 stdout。就是这样。

例如，您可以编写一个 shell 脚本来执行 pandoc

#!/bin/bash
pandoc -f [filter] --katex

站点初始化和启动器

当您执行 ssushi init [sitename] 时，sushi 将在项目配置文件夹和当前工作目录中搜索名为 "default" 的启动器，并将其简单地复制到 ./[sitename]。

您可以使用 --theme [starter_name/starter_path] 选项使用其他启动器。

请注意，使用 Cargo 安装后没有默认启动器，您应手动创建一个。