title: stgen3 author: Alistair Michael date-in-format: %Y date: 2021 notemplating: yes

stgen3 is a static site generator written in C++17, which uses the MultiMarkdown markdown parser to generate html. It aims to be fast, portable, and simple to use without configuration.

Features

• minimalistic templating system
• single static binary with no dependencies
• no config required
• templates and configuration exist alongside the markdown source
• configuration and templates are inherited down the directory structure
• Multimarkdown 6 syntax

Note: not all of the following functionality is supported yet.

Dependencies

• nlohmann json
• MultiMarkdown (clone into the directory MultiMarkdown and compile)
  • enable the token pool
• date.h (hopefully can be replaced with C++20 std::chrono one day)
• spdlog
• xxd
• lexbor
• duktape
• gnu source-highlight
  • boost-regex
• darkhttpd
• tinyxml2

Building

1. Clone project
2. Clone MultiMarkdown 6 into the folder MultiMarkdown, enable the token pool and compile it.
3. Ensure xxd is installed and run the script defaults.sh
4. mkdir build && cd build && cmake .. && make

• source highlight; installed from repos and linked as shared object
• lexbor; download and install or build from source and tell cmake to link the static binary

Basic Behaviour

Provided with a source directory, and an output directory, it recurses through the source directory compiling all markdown files to html and writing them to the destination directory, while copying all other files that are not on the ignored list.

Ignored files list:

• stgen.json
• anything ending in .template
• anything ending in .draft

Example

Running the following command where, the src and dest directories do not exist will create a new template site and build it into the dets directory.

$ stgen3 src dest

Usage

A tiny C++ static site generator.

Usage:
  stgen3 [OPTION...] [source] [destination]

  -h, --help            Show usage
  -d, --documentation   Show in-depth documentation
  -y, --noninteractive  Non-interactive mode (confirm everything)
  -n, --name arg        Site name, defaults to $source
  -u, --url arg         Site url, defaults to file://$destination
  -a, --author arg      Site author

A source and destination directory must be specified at compile time. Otherwise it assumes the source is the current directory and tries to find a config file that specifies the destination directory.

Configuration

Configuration files must be named stgen.json, and contain a json string-string map of attributes. These files can be placed anywhere in the site and their values are inherited down the file tree from that point. Repeatedly specifying the same attribute overwrites it.

The main attributes that should be set are

• url : the root url of the site
• name : the name of the site

For sub-directories, date can be set to determine its position in directory listings sorted by date.

Per-Article Configuration

Behaviour can be modified by configuration in the article's heading block. Heading blocks must start at the first line of the file. They may have --- on the first and last line.

• notemplating: disable templating for the file
• template: the html template to substitute content into

Templating

Syntax

Templates are surrounded by {{ }} braces, they consist of a command name followed by a colon separated list of arguments. Any starting or trailing whitespace on commands or arguments is ignored.

Templates can be escaped using a preceding backslash \{{ }}. By default, templating is run against all markdown documents only, and there is no way to disable this yet.

Variable substitution

Templates that are replaced with variables are simply a colon followed by the variable name.

{{ :date }}

Variables are set in both article headers and stgen.json.

Some variables are guaranteed to exist for any article in the system, this includes:

• url : The website's url, it defaults to the output directory absolute path
• page_url : The absolute url of the page.
• name : The name of the site, it defaults to the input directory name
• last_updated : Set to the last write time of the file
• current_file : The absolute path of the file in the compiling machine
• current_directory : the directory containing the file
• current file : the file being processed

Any metavalues set in page headers are accessible as variables. Generally title and date should be set.

• title: the article's title
• date: the publish date of the article
• author: the article's author

Directory listings

{{ postlist:relative/path/to/directory }}

Directory listings are sorted by the date of the post. Subfolders are ordered first by their date set in stgen.json, then the date of the most recent article in them, or placed last.

Dates are expected to be in the format yyyy-mm-dd.

Flow Control

{{ ifdef:attribute:
 Content to include
}}

The content of the last argument is included in the document if the specified attribute is set to something.

The ifndef command includes content if the attribute is not set. Template tags can be nested in this case.

{{ ifdef:title
    {{ :title }} 
}}
{{ifndef:title
    Title not set :(
}}

Template Files

The default template markdown files are written to can be overridden by writing a file called html.template. This needs to contain the variable substitution {{ :body }} in order to substitute the compiled markdown content into it.

Templates are also inherited down the directory hierarchy. For example, a template source_root/blogpost.html.template, can be used by a post located at source_root/posts/post.md, by setting the template field in its header block to blogpost.html.

---
title: Blog Post
date: 01-01-1970
author: Author
template: blogpost.html
---

[ source_root/posts/post.md ]

Drafts

Append .draft to the filename and it will not get compiled.