caltema

A simple static site generator leveraging markdown, pandoc and CI/CD automation

Overview

This is a Static Site Generator implementation which meets a few design choices:

1. All documents are authored in pure GFM
2. All processing is done with Pandoc
3. All stylistic elements are pure CSS, documents display w/o CSS if needed
4. All viewport sizes scale up/down to the device (desktop, mobile, tablet)

The intent is KISS in nature - very few moving parts, portable to any system and easy to implement. All documents can be authored and proofed within the web interface of Gitlab/Github Markdown itself, which should result in identical HTML output when processed by Pandoc.

The CSS styling can be customized to display as desired without requiring any special markup within the documents themselves. The intent is to not embed any markup which does not comply with the GFM specification.

Document Requirements

As the GFM spec does not support every possible HTML need, a few minor authoring requirements are required for best results:

• All markdown documents live in the src/ subdirectory
• Both src/index.md and src/license.md documents are expected to exist for basic navigation needs (HTML links in navigation template)
• The first line of each markdown document must begin with a single hash and space then title (# Title); this text will be extracted by the shell script and passed to Pandoc as the document's title HTML attribute
• Document references ending in .md) are transposed to .html); store links to MD internally (e.g.: [link](file.md) becomes [link](file.html) on the fly)

The processing rules for these requirements are located in bin/generate_html.sh; see the Visual Design section for additional files required for Pandoc processing to HTML.

Document Authoring Caveats

In order to maintain compatibility with viewing the documents in both Gitlab/Github web interface and generated HTML identically, a few caveats in document authoring.

• Table of Contents must be manually maintained; while Pandoc can generate one, the desire is to also have a usable TOC within the Gitlab/Github web interface itself. Pandoc will generate the exact same HTML anchors using the same logic methods as Gitlab/Github; it's possible to have Pandoc generate a TOC for you and cut&paste it back in, or 3rd party web tools exist which can also generate a TOC quickly
• Citations require double documenting in order to display as a section as well as inline; the markdown spec ("collapsed reference link") doesn't create a section out of the link reference definitions themselves

One example of Citations which will work inline and display as a section, other methods are possible:

## Some Section

This is a citation [(1)][c1] link which will use [(2)][c2] the URLs inline when viewed.

## Citations

  1. <https://example.com>
  2. <https://foobar.com>

[c1]: https://example.com
[c2]: https://foobar.com

A few other template files are required, see below.

Visual Design

The HTML generation is leveraging the Pandoc capabilities to include CSS and HTML templates around the generated document. The following are used:

• style/pandoc_html.tpl - core Pandoc template used during processing, a slightly customized version of the Pandoc default to remove hard-coded CSS values
• style/mdhtml.css - the CSS used, copied to ./public/ and linked to every generated HTML file
• style/body_before.html - included before the document content; implements the navigation bar and core CSS containers (div, article, etc.)
• style/body_after.html - included after the document content; closes the container tags (div, article, etc.)
• style/header_include.html - HTML header elements to display favicon and other various HTML metadata
• style/favicon.ico - the website icon, copied to ./public/ and linked to every generated HTML file

The document content generated by Pandoc has no CSS selectors used; the manipulation of visual style is handled by embedding the document content into a named container, then styling the container elements. The named files are used in bin/generate_html.sh and can be renamed easily.

Static Site Generation

The static site generation is managed by CI/CD:

• Debian latest docker image is used
• Latest pandoc DEB download is used

The process is designed to allow for local desktop development without a git commit, the CI/CD runs shell scripts to perform the work:

• bin/debian_pandoc.sh - prepares the image with the very latest Pandoc download available
• bin/generate_html.sh - builds the finished HTML+CSS into ./build/

Commits to master trigger CI/CD to publish new Pages in it's entirety using the included Gitlab .gitlab-ci.yml configuration, which runs the above shell scripts.

For desktop development, it's only needed to set up Pandoc once, then use bin/generate_html.sh from the top level directory to regenerate the output for proofing. All output goes into the public/ subdirectory which is excluded from git operations (.gitignore), one can rm -rf ./public routinely.

SPDX-License-Identifier: MIT