quest/README.md

BASEMENT QUEST

the kids in the basement are gonna play some rpg in on the listserv

about

this is an iteration on my usual pandoc static site generator

order

instead of relying on literally naming files 0001-me-first.md and 0002-me-second.md so they are concatenated in the correct order¹, this repo introduces basement.order

in the file, you can ls ./**/** 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 each time you add a document to the source.

documents

documents are markdown with yaml frontmatter. they are compiled into:

• html with spoilers for game ref
• 'public' html sans spoilers for players
• 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 of rss. probably needs to be in date -R format.
• public² (bool) (optional): spoiler-free content
• syndicated² (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 because an all-caps macro name is probably safe, but 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.

---

1. 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/ ↩︎

2. These are not true booleans. Pandoc templates cannot evaluate the value of a field. Only its presence. This could say public: astronauts or syndicated: 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. ↩︎