中文README

sūshì

Sūshì is a simple but customizable static site generator / blog generator written in Rust.

Installation

Install with Cargo (Recommended)

cargo install sushi-gen

ssushi will be installed in .cargo/bin. Now check the installation.

ssushi --help

Compile from Source Manually

Clone this repository and cd into it:

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

And build it with Cargo:

cargo build --release

The binary executable ssushi will be placed in target/release

Quick Start

For Linux users:

1. Install sushi

2. Get a starter (or so called "theme"), for example

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

   Copy the starter into config directory and rename it to default. On Linux, it is $XDG_CONFIG_DIR/sushi-gen or $HOME/.config/sushi-gen. (Refer to ProjectDirs in directories). Don't forget to install all dependencies of the starter.

3. Initialize your site

   ssushi init [your_site_name]
   

4. Build the site

   ssushi build
   

5. Now the site is generated into _gen folder. You can install sfz to serve the site.

   cargo install sfz
   sfz -r _gen
   

How does sūshì work?

Site Structure

A Sūshì site might look like this:

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

Actually only _converters, _includes, _templates and _site.yml are necessary and should NOT be renamed. Once sushi starts, it reads these files and folders first and load them into memory.

Templates (written in liquid template language) and partials (in liquid too) should be stored in _templates and _includes respectively. Site configurations are written in _site.yml. _converters stores executables for converting page files into HTML pages (i.e. markdown parsers).

Note that sūshì does not parse markdown (or any other format) directly, what it does is simply compiling templates you provide and insert the converted page contents into them. You can write your parser, or write a simple script to execute some parser (i.e. pandoc).

After reading these important configurations, sushi convert all pages found by execute the converters. Folders and file start with . or _ will be ignored. All file that are not recognized as "page files" will be copied directly to the corresponding locations.

Generated site is put in _gen folder.

Site Configuration

_site.yml might look like this:

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

Page Front Matter

Front matter contains the configuration of the page.

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

Write Templates

Liquid

Sushi uses the rust implementation of liquid template language. For syntax of liquid, please refer to the documentation of liquid languague and liquid crate.

Global Objects

Sushi offers some global liquid variables.

Besides the key-value pair defined by user in _config.yml and front matter, site and page object contains some generated information.

page.search_text is meant to used for implementing search functionality

sitetree object

taxo object

Template Front Matter

Template inheritance is supported, which is similar to that of Jekyll. If template post inherites template page, the render result of post will be the content inserted to page.

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

Add Partials

If a snippet of code is used by multiple templates, it is recommended to split them to a partial file. All partial file should be put in _includes folder.

For example, if header.liquid is put in _includes folder, you can use {{ include header }} in your template to include it.

Paginator

Paginator is used to split a page into mutiple pages (for example, when showing a super long list of page titles in home page).

Usage of paginator is a little bit complex.

First, paginator of sushi is based on "list", it splits the list into multiple "batches". So you should put the list you want to split into page front matter.

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

And then, use the paginator object in your template. For example:

{% 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 %}

After pagination, page test.md might be split into

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

Write Converters

Writing converters is quite simple. A converter is a executable reads input from stdin and writes output to stdout. That's all.

For example, you can write a shell script to execute pandoc

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

Site Initialization and Starters

When you execute ssushi init [sitename], sushi will search for a starter named "default" in project config folder and current working directory, and then simply copy it to ./[sitename].

You can use --theme [starter_name/starter_path] option to use other starters.

Note that there is no default starter after installation with Cargo, you should create one manually.