Every file in this git repository is available via http from secularsolstice.github.io. Most of the files people are expected to look at are in the gen directories, but some (such as index.html and theme.css in the root directory) are not. This is a github feature called "Github Pages".
How that works behind the scenes I don't know. It does seem to involve copying data on a timer, because there is an intermittent delay between pushing content and that content being visible on the website.
Each song folder has a Makefile which mostly imports scripts/Makefile.common. It sets two variables first, PREFIX which gets prepended to output files and FILES_TO_LIST which makes dependency detection work.
Rules for converting formats live in the common makefile. These include:
chord-sheet-2col.pdf in FILES_TO_LIST)Each song makefile must also provide a rule for gen/${PREFIX}lyrics.txt which contains the lyrics in simple text format. This could be as simple as copying a file, or could use one of the lyric-extractor scripts in the scripts directory. Most of these extractions are reasonably straightforward, but the lilypond one is a bit more complicated. It does not parse the entire lilypond format, but recognizes lyricsmode commands. It expects verses to be in order, and choruses to be named "chorus".
The common makefile then invokes scripts/create-index.sh to create index.html and scripts/create-thumb.sh to create thumb.png. The latter is shown in the preview if the song is shared on Facebook or Twitter.
So far as the scripts are concerned, the only difference between a speech and an activity is that one is on the All_Speeches list and the other on the All_Activities. Either way, it's a simple markdown file.
Lists, whether All_* or a program, are processed by scripts/process_list.py. This extracts the title, creator and (for songs) synopsis from the item's own files. This helps ensure that everything stays in sync.
The script is still in python 2. Hope that doesn't come around to bite us.
The list of programs is generated by scripts/create-program-list.sh invoked from the Makefile in misc. The columns are handled by a crude hack that could use improvement.
Additional documents, like this one, live in misc as simple markdown. The table of contents in the How document is manual -- it just wasn't worth wrestling the pandoc --toc flag into submission.
The list builder tool is static html and javascript that lives in misc, but its autocomplete data is generated by the misc Makefile (using scripts/gather_lists.sh).
When you push, a github action is triggered. Through this, a github server spins up a docker container, pulls the repo, runs make all, adds/commits/pushes the results, and spins down the container. This is all defined in .github/workflows/autogen.yml.
The docker image is defined in .github/workflows/Dockerfile, but github doesn't look at the Dockerfile directly. Instead it pulls the image from dockerhub.
To view the status on an autobuild, click the "Actions" tab on github, then the push of interest, then the "build" job in the box on the left. Github supports having multiple jobs in one workflow, and the UI is optimized for that case, even though I can't think of a case where it's useful.
By default, everything appears light-on-dark, as is appropriate for the longest night of the year. But this caused throuble for some people, especially for copy-pasting into wysiwyg word processors. So there's now a button to toggle to a dark-on-light color scheme.
The button and its behavior are all in the file theme-switcher.js, which uses raw javascript for its DOM manipulations.
The light theme is implemented by sticking a light css class on the root html element, and letting ancester-based css selectors do the rest of the work.
The user's chosen theme is stored in a cookie, but can be overridden by appending ?light or ?dark to the url (to allow convenient iframing).