16 releases (8 breaking)
0.9.0 | Oct 24, 2024 |
---|---|
0.7.0 | Aug 1, 2024 |
0.6.0 | Mar 31, 2024 |
0.5.0 | Nov 7, 2023 |
0.1.1 | Dec 16, 2018 |
#37 in Template engine
35KB
782 lines
Site
Site is a fast, simple, and opinioned static site generator, written in Rust. Highlights include:
- Write your content in Markdown format. Site is using pulldown_cmark as a markdown parser with extensions.
- Uses Jinja2 as a template language. Site is using tera template engine.
- Very simple. Blazingly fast. Build articles in parallel.
- Inspired by Pelican, which is a static site generator written in Python. Site has a similar concept of Articles and Pages.
- Inflexible and opinioned by design. Site implements only what the author needs to build a simple static site, like https://hayatoito.github.io/. If you want to customize, I'd recommend to fork Site itself. Site is intentionally kept very small so you can understand codebase and customize it easily.
Install
cargo install site
Usages
No documentations yet.
Meanwhile, as a living document, use hayatoito/hayatoito.github.io as your starter boilerplate. https://hayatoito.github.io/ is built from that repository.
Folder structure
root_dir/
- src/
- (Put your markdown files here)
- template/
- (Put your template files here)
-
src/
is a folder where your all markdown files live. They are converted into HTML files, using Jinja2 template, and are copied into the output directory.Any other resources in
src
directory are also copied to the output directory. -
template/
is a folder where jinja2's template files live.
Markdown format
Site
uses markdown.
# Article title
<!--
date = "2021-12-01"
-->
# Section
Hello Article!
- hello
- world
Nothing special except for:
- The first section is considered as a title of the article.
- Metadata, such as
date
, follows.
Metadata
TODO: Explain
Name | Description | Default value |
---|---|---|
page |
false | |
date |
(date is mandatory unless page: true ) |
|
update_date |
NA | |
author |
NA | |
slug |
The page's URL | Calculated by a relative PATH to src |
draft |
Skip this markdown | false |
template |
Template file to use in template folder |
article or page |
Pages
If a markdown's metadata contains page: true
, Site consider that the
markdown represents a page, instead of an article.
# Page title
<!--
page = true
-->
# Section
Hello Page!
- hello
- world
The differences between article and page are:
- A page will not be included in
articles
template variable. Neither inarticles_by_year
. - A page doesn't have to contain
date
metadata.
Template variables
TODO: Explain
Name | page | article | Description |
---|---|---|---|
entry |
x | x | Represents an article or a page (its metadata and content) |
site |
x | x | Site configuration given by --config parameter |
articles |
x | The list of the articles | |
articles_by_year |
x | The list of { year, articles} |
articles
andarticles_by_year
are only available in a page. In other words, an article can't know other articles.
entry
In addition to its metadata, entry
contains the following fields:
Name | Description |
---|---|
entry.title |
Title |
entry.content |
Generated HTML |
entry.toc_html |
Generated TOC (if toc: true ) |
Build
CLI
site build --root-dir . --config=config.toml --out-dir out
root-dir
should contain src
and template
folders.
See Make.zsh for the example CLI usages for various tasks.
GitHub Action
You can also use GitHub Action to build and deploy automatically if you are using GitHub Pages. See build.yml as an example.
Dependencies
~9–18MB
~242K SLoC