site

Crates.io	site
lib.rs	site
version	0.9.0
source	src
created_at	2018-12-13 13:31:41.109895
updated_at	2024-10-24 13:38:58.470147
description	A simple, fast, opinioned static site generator
homepage
repository	https://github.com/hayatoito/site
max_upload_size
id	101749
size	57,431

move-crate-owners (github:diem:move-crate-owners)

documentation

README

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 in articles_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 and articles_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.

Commit count: 99