wellquite.org/ssg

Static Site Generator

This project is a Static Site Generator. It is written in Go, and makes heavy use of Go's templates; you will need to be familiar with these to be able to use this project. They are a little weird in places.

Install the ssg command by running:

$ go install wellquite.org/ssg/cmd/ssg@latest

The command ssg has the following flags:

• -in The directory to use as input. Always required.
• -out The directory to use for output. Mutually exclusive with -serve.
• -serve Takes an optional port number. 1313 is the default. If this flag is given, then ssg runs as a webserver and rebuilds the site everytime it detects a change within the input. Mutually exclusive with -out.
• -log Specify the log level. Default is info. debug and trace provide more verbosity. warn and error provide less verbosity.

The go doc shows all the fields that are available to the templates.

Semantics

• Every file found (recursively) within the input directory will have a corresponding file in the output directory, unless it has parseable meta-data section and that meta-data section sets output = false.
• For a file to have parseable meta-data, it must be the case that valid TOML exists at the start of the file, demarkated by a line with --- and nothing more, before and after the TOML.
• If the input file does not have a parseable meta-data section then the file is copied verbatim to the output directory.
• If the input file has a .md extension then it is required the content of the file is markdown (after the meta-data section).
• If the input file is a markdown file, and has path foo/bar/baz.md then its output path will be foo/bar/baz/index.html. All other files have their output path equal to their input path, relative to the input directory.
• If an input file has parseable meta-data and that meta-data specifies a non-zero date field, then the input file is considered a Post and a Page. Otherwise, it is considered a Page only. This affects which fields the file appears in within the .Global template field.
• The inner template is the content of the input file after the meta-data section. If the page has no parseable meta-data then it is not considered to have an inner template (or outer template).
• The outer template is indicated by the field template in the meta-data.
• All files with parseable meta-data are loaded as templates, and the template name is the file's path, relative to the input directory.
• If an input file has parseable meta-data and that meta-data does not specify a summary field and the input file is a markdown file, then the summary is automatically determined from the page content (after the inner template has been run but before the conversion to HTML), by taking the plain text from the start of the content to the end of a sentence that finishes after at least 70 words from the start.

Order of operations

1. All files in the input directory are loaded and parsed before any templates are run. Thus all templates have access to the meta-data of all input files.
2. Once all files have been loaded, the inner templates for all markdown files which have output = true are run. The result of running these inner templates must be valid markdown. The markdown is then converted to HTML, and is stored in the ContentInner field.
3. Next, all files have their inner templates run if they've not been already run, and then their outer template if it has been specified. The result of running the outer templates is stored in the ContentOuter field. If no outer template is specified then the ContentOuter field will have the same value as the ContentInner field.
4. After that, all tag-templates are run.
5. Finally, write everything to the output directory.

Examples

Example 1

This example, if it exists as a file within the input directory, would have a corresponding file in the output directory, which would contain the result of transforming this input file from Markdown to HTML.

Example 2

This example shows how to generate an RSS feed for all the Posts. You might put this example in a file rss.xml:

---
output = true
---
<?xml version="1.0" encoding="UTF-8" ?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
  <channel>
    <title>{{ html .Site.Title }}</title>
    <link>{{ .Site.BaseURL }}</link>
    <description>Recent content on {{ html .Site.Title }}</description>
    <generator>{{ html .Generator }}</generator>
    <language>en-us</language>
    <copyright>Copyright © {{ .Now.Year }}, {{ .Site.Author }}</copyright>
    <lastBuildDate>{{ .Now.Format .RFC1123Z }}</lastBuildDate>
    <image>
      <url>{{- .Site.BaseURL -}}logo.png</url>
      <title>{{ html .Site.Title }}</title>
      <link>{{ .Site.BaseURL }}</link>
    </image>

    <atom:link href="{{ .Page.AbsoluteURL }}" rel="self" type="application/rss+xml" />

    {{- $dot := . -}}
    {{- range $post := .Global.Posts }}
    <item>
      <title>{{ html $post.Meta.Title }}</title>
      <link>{{ $post.AbsoluteURL }}</link>
      <pubDate>{{ $post.Meta.Date.Format $dot.RFC1123Z }}</pubDate>
      <guid>{{ $post.AbsoluteURL }}</guid>
      <description>
        {{ $post.ContentInner | printf "%s" | html }}
      </description>
    </item>
    {{- end }}
  </channel>
</rss>

Example 3

The inner template can call other templates. For example, this file could be at posts/series/onions/post3.md:

---
title = "Onions: the revenge"
date = 2021-12-09T11:01:09Z
tags = ['onions']
output = true
template = "templates/post.html"
'''
---

In this series:

{{ template "templates/list-pages.md" (index .Global.PostsByTag "onions").OldestFirst }}

For many people, onions make them cry...

It specifies a outer template that should be found at templates/post.html (which presumably is responsible for turning the HTML-from-markdown into a fully valid HTML page); and in the inner template, it calls templates/list-pages.md. That file could look like this:

---
output = false
---

{{ range $page := . }}
* [{{html $page.Meta.Title}}]({{$page.AbsoluteURL}})
{{- end }}

It sets output = false because this file is only useful as a template to be used by others, so it should not have a corresponding output file for itself. This template generates markdown (which is hinted at by the fact it has a .md extension). So, the inner template of post3.md is run (which calls templates/list-pages.md), and the result of that is assumed to be valid markdown and then converted to HTML. The result of all of that is passed to the outer template (templates/post.html), and the result of that will be stored in the output directory at posts/series/onions/post3/index.html.