2 releases
Uses new Rust 2024
| new 0.1.1 | May 7, 2025 |
|---|---|
| 0.1.0 | May 7, 2025 |
#46 in Template engine
18KB
360 lines
ssg08
A static site generator, configured via a simple template.
Disclaimer
I will likely continue to alter this program significantly as I use it. If you find it useful, please consider freezing your version and/or forking, in the meantime. Thanks!
Installation
cargo install ssg08
See ssg08 --help for usage information.
Overview
Let us have the following input tree.
input
├── about.md
├── index.md
├── main.css
├── posts
│ ├── code.md
│ ├── code
│ │ ├── langs.md
│ │ └── ssgs.md
│ ├── music.md
│ └── music
│ ├── deafheaven.md
│ └── gybe.md
└── assets
├── favicon.svg
└── cover.jpg
Each Markdown file of the input tree is converted to an HTML file in the same
position of the output tree. If a subtree is placed with a like-named Markdown
file at the same level (ex. input/posts/code and input/posts/code.md), a
listing of the subtree's Markdown files will be appended to the like-named
Markdown file (here, a feed which contains langs.md and ssgs.md would be
appended to the contents of code.md). A subtree which contains Markdown
files, and which does not have a like-named Markdown file at the same level,
is parsed as an error. Any non-Markdown file is copied as is, into the same
position of the output tree as in the input tree. The output tree would then
be the following.
output
├── about.html
├── index.html
├── main.css
├── posts
│ ├── code.html
│ ├── code
│ │ ├── langs.html
│ │ └── ssgs.html
│ ├── music.html
│ └── music
│ ├── deafheaven.html
│ └── gybe.html
└── assets
├── favicon.svg
└── cover.jpg
The only change visible in the file hierarchy is the transformation from Markdown to HTML.
Markdown
Each Markdown file must begin with the following.
---
title: TITLE, plaintext only
date: DATE, in YYYY-MM-DD format
---
The parser otherwise accepts CommonMark, with the following extensions.
- Tables
- Footnotes
- Strikethrough
- Tasklists
- Smart punctuation
- Math (LaTeX will be tagged, but is not expanded)
- Superscript
- Subscript
See the pulldown_cmark documentation
for more information.
Templates
ssg08 takes a template parameter to base HTML generation upon. It may contain
the following expansions.
| Expansion | Function |
|---|---|
{{ title }} |
The title value of the Markdown file's YAML metadata. |
{{ date }} |
The date value of the Markdown file's YAML metadata. |
{{ navigation }} |
A navigation bar generated from the site's top-level pages. |
{{ content }} |
The HTML content of the page, excluding feeds. |
{{ posts }} |
Post feeds generated from like-named subtrees. |
The navigation bar is not wrapped in <nav> tags. Each post of a feed is of
the following form.
<div class="post">
<span class="post-title">
<a href="LINK">
TITLE
</a>
</span>
<span class="post-date">
DATE, in YYYY-MM-DD format
</span>
</div>
The following is a very simple template example.
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="date" content="{{ date }}">
<title>{{ title }}</title>
</head>
<body>
<nav>{{ navigation }}</nav>
{{ title }}
{{ content }}
{{ posts }}
</body>
</html>
Dependencies
~20–28MB
~365K SLoC