SWGIG

Static Website Generator I Guess, a static website generator of questionable veracity and dubious tooling

Why?

I just wanna write Markdown files for my site. The little bit of tooling around them to make it more convenient and readable is that much better!

Build

To build the site, make / make all. Most of the work can be done in parallel with make -j.

The makefile has a dev target which starts a Docker container, forwarding an Apache webserver from its port 80 to your host's port 8080. This means you access the site at localhost:8080/.

Setup

Here's everything to fix:

git grep -n "TODO" | sed 's/README.md.*//g' | awk 'NF'

pages/index.md:2:title: TODO
static/LICENSE.txt:1:TODO: Your license here for your creative content.
static/humans.txt:2:    TODO
static/style.css:1:/* TODO: This is my own CSS. You may want to do some thing else! */
templates/blog_header.md:2:title: TODO's Blog
templates/default.html:12:    <meta property="og:title" content="TODO - $pagetitle$" />
templates/default.html:15:    <meta property="og:url" content="https:/TODO/$directory$" />
templates/default.html:19:    <meta property="og:site_name" content="TODO" />
templates/default.html:21:    <meta property="og:description" content="TODO" />
templates/default.html:23:    <title>TODO - $pagetitle$</title>
templates/default.html:24:    <link href="TODO" rel="canonical" />
templates/default.html:36:      <h2><a href="/">TODO</a></h2>

Also, the avatar.jpg and favicon.ico say TODO. You may re-design to remove the avatar, though.

Customizing

Everything you'd do with a Markdown file can still be done. Here's the extras:

Necessary information

• Add a new page by creating a markdown file under the pages dir.
• Add a new directory by making that directory under the pages directory. Note that the directory must be populated with at least one markdown file.
• Adding an index.md to a directory creates a link to that directory: /dir/
  • mkdir -p pages/art && touch pages/art/index.md pages/art/other.md will link /art/ and /art/other.html
• Every markdown file needs a frontmatter of the following form at the top of the file:

---
title: My Title
author: My Name
date: 2023-03-07
---

Note title is needed for all files; date is also required for blog posts.

Extra Syntax

These two are from pandoc:

You can add <div> (multiline) with a class with the following syntax:

::: classname

My content

:::

You can add <span> (inline) with a class with the following syntax:

[My content]{.classname}

Extra Frontmatter

Add extra CSS by providing the name of a css file in the extracss field of your file's frontmatter. That file must exist in static. For example:

---
---
extracss: artstyle
---

You can add extra functionality to the frontmatter by checking for the variables you specify in templates/default.html.

Special strings

Any file may have a table of contents by adding the line <!-- toc -->. On build, markdown-toc will replace that with a generated table of contents based on the file's headings.

Blog posts with a line of text then <!-- preamble --> between the frontmatter and content, will have that line appear on the blog below the entry.

Other notes

• If you create a file, you must link to it with .html, NOT .md.
  • Github Pages's router lets you omit the .html, but the dev server will not. You could add that with these instructions if you wanted, but I didn't want to have an extra Dockerfile.

Deployment

See the github workflow. It'll happen automatically when you push.

Tools

• Make
• Pandoc, markdown to HTML
• markdown-toc, make tables of contents
• htmlmin, deliver tinier HTML
• bash for a some scripts to generate certain pages
• docker for dev

Other thoughts.

If you really want a static website generator you know all the ins and outs of, pick some tools off the shelf and build one. make is your friend. If you just want it to work, slap together Sveltekit or Astro with MDsveX or mdx, respectively, and you're set.