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).