Static Website Generator I Guess, a static website generator of questionable veracity and dubious tooling
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!
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/.
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.
Everything you'd do with a Markdown file can still be done. Here's the extras:
- 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.
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}
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
.
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.
- 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 extraDockerfile
.
- Github Pages's router lets you omit the
See the github workflow. It'll happen automatically when you push.
- 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
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.