The website for the Public Works Book Club, where we only read works in the public domain.
Here's how you do stuff:
# installs everything that you need
pnpm install
# Initialize comments submodules if needed
pnpm initialize
# builds once, output will be in the `public` directory
# Use BUILD_OPTS to pass options to the zola build command
# Note: the search index is built from crawling the output of the zola build
pnpm build
# starts a local server that binds to `localhost:2665`, and watches the respective directories and rebuilds upon every change
# Use SERVE_OPTS to pass options to the zola serve command
# Note: the search index is only built once
pnpm serveFor example, you can run SERVE_OPTS="--interface 0.0.0.0 --base-url 192.168.0.1" pnpm serve and then go to localhost:2665 in your browser to see the website, as well as access from a mobile device on the same network. As you make changes to the code or content, the website will be updated.
Any changes need to recorded in the CHANGELOG.md file, with the corresponding version number reflected in the package.json file.
Some notes on versioning:
- adding content to existing links is just a bump in patch version, i.e.
nn.nn.++ - changing links, including anchors, is a bump in minor version, i.e.
nn.++.nn - fundamental changes in the site's tech, that makes it incompatible with prior versions is a change in major version, i.e.
++.nn.nn
For example, releasing a huge new initiative to launch our theoretical youtube channel would be a minor version change, however keeping the site exactly the same but moving the static site generator from zola to hugo would be a major version change.
(These guidelines are subject to change 😂)
Content is stored in markdown text files located within the content directory. Files named _index.md are called "sections", and files by any other name ending in .md are called "pages". For more information you can read the zola documentation. It is written in markdown and inserted into the html via the "template", which is indicated on the top of the content.
Works that have been read in the club are located under [/content/works/](./content/works/). Each page within there has front matter that is designed to be read by a macro (see macro/json-ld) that then outputs json-ld. This constitutes a bibliography of abstract works that can be cited throughout other parts of the site and is meant to work as a single source of truth.
See Demosthenes - On the Crown as an example.
The front matter for each of the works use common english terms such as "Ancient Greek" for language or "funeral oration" for literary form. These terms are then defined as a vocabulary under data/vocab where additional data and links can live. This allows common terms to be used and promotes reuse across the site.
Note: controlled vocabulary that have non-ascii characters should use an ascii-ized name and a label field in their vocabulary. E.g. "Diogenes Laërtius" should be referred to as "Diogenes Laertius" for coding tasks, and access the label = "Diogenes Laërtius" for displaying the name correctly.
JSON-LD is designed for creating links between pieces of data representing relationships. Here are some sources that can be reused.
- Wikidata - for general linked data
- Getty Vocabularies - for literary terms
- Lexvo - for languages
Templates are in the templates directory. Their purpose is to decide where in the html the content goes. The content is accessible to the template as a variable named either section.content or page.content, depending on the context.
This website uses tailwindcss for most of its styling. Additional styling can be added to the css/input.css file, but usually it is not necessary to add any custom styling. This file is read by tailwind which adds whatever additional styling is referenced in the html, resulting in a file called style.css, which is what is used by the website.
The tailwind typography plugin is used to style content that is generated from markdown. Any child elements that are nested within an element that has the class prose will receive the styling. The default styling can further be customized in the @theme directive located within css/input.css.
The search works as a separate build process. After the site is built with Zola, it's crawled by pagefind which generates a search index and injects a custom UI. The UI has been adapted for the site in the input.css file. The main thing to be aware of is that this is that the crawling is done in a separate step from the building. In the case of pnpm serve the site is built and crawled once, then the output of that is copied over to the static directory. This more or less allows one to iterate on the website and still see the search index, however if you need live updates of the search related stuff, you will have to re-run the command each time.
While serving you can navigate to /pagefind/playground/ to introspect the search results.
- zola@0.20.0
- node@20.0.0
- tailwindcss@v4
- tailwind typography plugin
- prettier
- pagefind
This site is deployed using Cloudflare pages. Access is granted to the project's code repository by this site's admin's Cloudflare dash. When a branch is pushed a build is triggered and a new version of the site is deployed. If the branch is the "production" branch then the new version will be deployed at https://b00k.club, otherwise it's deployed to some throwaway branch, usually a truncated version of the version's git branch.
Here are some additional things to know about deployments
- There is a file called
_headerswhich is a convention used by Cloudflare pages to set HTTP headers for the static site ZOLA_VERSION=0.20.0must be explicitly set in Cloudflare pages build settings- There's a file,
CHANGELOG.md, that helps track what's changed as the site evolves
- This site was initially generated using a GitHub template for making zola static sites that work well with tailwindcss.
- The
pnpm servescript runs two long-running tasks in parallel and allows both to write simultaneously to STDOUT by using a mixture ofwaitand sending jobs to the background - Sometimes important changes for styling need to be made in the
@themedirective - Builds can break when deployed, and a common place to look is needing to add or update an environment variable for Cloudflare's "pages" product