Dozens B. McCuzzins e6f7263de2 | ||
---|---|---|
assets | ||
assetsrc | ||
doc | ||
includes | ||
src | ||
templates | ||
www | ||
LICENSE | ||
README.md | ||
basement.order | ||
justfile | ||
macros | ||
macros.m4f |
README.md
note: this readme is spoiler-free. but the contents of this repo are not. if you are one of my current players, proceed at your own peril.
BASEMENT QUEST
the kids in the basement are gonna play some rpg on the listserv
about
this is an iteration on my usual pandoc static site generator, with---as usual---just a sprinkling of m4
getting started
you will need:
- pandoc v2.19.2: markdown to html and rss
- m4 v1.4.6: macros. currently used for generating statistics in
about.md
- (optional) just v1.4.0: a command runner. optional, because you can just manually run all the commands in the justfile.
read the justfile or run just
to see what commands are available.
page order
instead of relying on literally naming files 0001-me-first.md
and 0002-me-second.md
so they are concatenated in the correct order1, this repo introduces basement.order
in the file, you can ls src/**/**
to list all files, and then order them in the way that is most pleasing to you
NOTE: you will of course need to update basement.order
with the new docoument path every time you add a document to the source.
documents
documents are markdown with yaml frontmatter. they are compiled into:
www/spoilers.html
: html with spoilers for game refwww/index.html
: 'public' html sans spoilers for playerswww/rss.xml
: rss feed for syndicated documents
metadata
every markdown document includes yaml frontmatter metadata
fields:
- title (string): title of the document. mostly for rss item id
- created (date): date of creation. probably needs to be in
date -R
format. - updated (date): date of most recent update. mostly for rss. probably needs to be in
date -R
format. - public2 (bool) (optional): is this spoiler-free content appropriate for public consumption?
- syndicated2 (bool) (optional): should this document be included in the rss feed?
example:
---
title: notes
created: 2022-07-24
updated: 2022-07-25
public: yes
syndicated: yes
---
macros
you can define macros in /macros
and then include them in your documents to be expanded while building.
i arbitrarily adopted a "zxMACRONAME" naming convention with a 'zx' namespace because while an all-caps macro name is probably safe, it is even safer with a random zx
in front of it.
also it gives you good autocompletion if all your macros have the same prefix / namespace.
i just recently learned about m4 frozen state files, and have started using loading state from macros.m4f
https://web.mit.edu/gnu/doc/html/m4_14.html
there are only marginal improvements to build times because of this; the slowness comes from expensive system calls, not from a massive amount of macros.
but so, if you add macros or make changes to the existing ones, you will need to run just freeze
prior to rebuilding.
-
this is the strategy i employed in forest. it worked okay, but left something to be desired. namely, the flexibility to insert new files at random locations, or to rearrange existing files, without having to rename a bunch of files. i'm not sure this current solution is the best one. but it is an improvement i think. https://git.tilde.town/dozens/forest/ ↩︎
-
These are not true booleans. Pandoc templates cannot evaluate the value of a field. Only its presence. This could say
public: astronauts
orsyndicated: spaghetti
. You can only set these flags on and off by including or omitting the field entirely. This is probably not the way you would expect it to work, so watch out. Incidentally, this is the same way that the stateless templating engine mustache works. Pandoc templates bring so little to the table that it might be easier in the future to just use recfiles instead of markdown+yaml, and pipe it through mustache or recfmt. ↩︎