Readerly is a free theme for people who love books, for WordPress, Hugo and Ghost. It is built for a book blog first, and it also gives you an author website and a reading log. Each use is optional: the theme creates no pages, posts or categories, and every section can be removed. It comes in two styles, Paper (light) and Lamplight (dark), and bundles its fonts, so it makes no third-party requests.
The WordPress theme requires WordPress 6.9 and PHP 7.4, under GPLv2 or later. The Hugo theme runs on Hugo 0.146.0 or later and the Ghost theme on Ghost 6, both under the MIT License.
| Folder | What it holds |
|---|---|
design/ |
Seven static HTML pages (blog home, review, author, reading log, archive, page, 404), their CSS, script and fonts, tokens.json, and demo/, the content of the Marginalia demo that the Ghost demo loads. This is the approved visual reference and the source of every generated file. |
wordpress/ |
The WordPress theme. Its contents are what ships; wordpress/readme.txt is the WordPress.org readme. |
hugo/theme/ |
The Hugo theme, published as listofbooks-net/hugo-theme-readerly, with its demo site, Marginalia, in hugo/theme/exampleSite/. |
hugo/fixtures/ |
Sites that only the checks build: bare (a title and nothing else), quickstart (what hugo new site and hugo new content make), sparse (one review per missing field), paginated (a custom pager path) and no-credit (the credit partial emptied). |
ghost/ |
The Ghost theme. Its contents are what ships; ghost/README.md is the theme's documentation. |
tools/ |
The generator, the checks that CI runs, the zip builder, a local WordPress, the Hugo build images and a local Ghost. None of it ships. |
design/ is the single source for colors, type, spacing, radii, fonts, CSS and the theme script. One command writes every file derived from it:
design/assets/css/tokens.cssanddesign/assets/css/fonts.css- the palette, presets and font faces in
wordpress/theme.json, and the Lamplight stylewordpress/styles/lamplight.json wordpress/assets/fonts/hugo/theme/assets/readerly/css/readerly.css(fonts, tokens anddesign/assets/css/style.css) andhugo/theme/assets/readerly/js/theme.js, the theme's fonts and images inhugo/theme/static/readerly/, and the demo's covers and images inhugo/theme/exampleSite/static/assets/ghost/assets/css/readerly.css(fonts, tokens anddesign/assets/css/style.css),ghost/assets/js/theme.js, and the Ghost theme's fonts and images
node tools/build-tokens.mjs # regenerate
node tools/build-tokens.mjs --check # exit 1 if a generated file is out of datenode tools/ghost-locales.mjs [--check] does the same for ghost/locales/en.json, from the strings in the Ghost templates.
Edit the source in design/, rerun the command and commit the generated files. Do not edit those files by hand. The design pages link design/assets/css/demo.css, which holds the demo-bar rules that no theme ships.
You need Docker. The script starts WordPress with WP_DEBUG on, installs it, activates the theme and loads demo content (ten reviews, four pages and a menu). The site opens at the URL it prints, with the login admin / admin.
tools/wp-dev/wp-dev.sh up # start, install, seed
tools/wp-dev/wp-dev.sh style lamplight # or: paper
tools/wp-dev/wp-dev.sh check # Theme Check against the theme
tools/wp-dev/wp-dev.sh wp <wp-cli arguments> # any wp-cli command
tools/wp-dev/wp-dev.sh down # stop, keep the data
tools/wp-dev/wp-dev.sh clean # stop and delete the dataThe theme folder is mounted read-only, so edits show up on reload. tools/wp-dev/check-pages.cjs screenshots every demo page at 1280 px and 390 px and checks for overflow, broken images, console errors, third-party requests and the footer credit; see the header of that file for usage.
CI is .github/workflows/ci.yml, run as GitHub Actions on self-hosted runner-up machines for pull requests and pushes to main. Push the branch, then read the result with gh pr checks and any failure with gh run view --log-failed. To check locally, run the commands each job runs, for example:
node tools/build-tokens.mjs --check
npm ci --prefix tools && node tools/check-theme-json.mjsCI checks that the generated files are up to date, that theme.json and the style files match the WordPress schema (npm ci --prefix tools && node tools/check-theme-json.mjs), that every PHP file passes php -l on PHP 7.4 and 8.4, and every Hugo and Ghost check in the sections below.
You need Docker and Node. The script builds two images from the official extended Hugo release, each checked against its published checksum: the theme's minimum version (0.146.0, which must equal [module.hugoVersion] min in hugo/theme/hugo.toml) and the latest version the theme is tested on (0.169.0). Both load the theme from hugo/theme/, so nothing is downloaded from the published repository.
tools/hugo-dev/hugo-dev.sh images # build the two images, once
tools/hugo-dev/hugo-dev.sh build # build every site on both versions into tools/hugo-dev/out/
tools/hugo-dev/hugo-dev.sh serve demo # serve the demo at http://localhost:4000/sub/build builds the demo and the five fixtures under the baseURL http://localhost:4000/sub/. A build fails when Hugo exits with an error or writes anything to stderr, where it prints every warning.
To run the checks, install the tools and point CHROMIUM_PATH at a Chromium:
npm ci --prefix tools
CHROMIUM_PATH=/usr/bin/chromium tools/hugo-dev/hugo-dev.sh checkcheck builds, then runs tools/hugo-dev/check-builds.mjs:
- Each site's HTML is the same on both Hugo versions, whitespace aside.
- Every internal link and asset resolves to a built file under the baseURL.
- Every attribute parses, no heading is empty, and each fixture's own cases hold: quotes and
</script>in titles and authors, a plain-string author and a menu of plain URLs on a site made withhugo new site, a custom pager path, and no credit link once the partial is emptied (check-markup.mjs). - The demo has the same markup as the seven design pages (
check-parity.mjs). Each allowed difference is inparity-exceptions.jsonwith its reason. - Every page of every site but
no-creditpassestools/wp-dev/check-pages.cjsat 1280 px and 390 px, in Paper and Lamplight: no overflow, broken images, console errors or third-party requests, one h1, no empty headings or sections, and exactly one footer credit.
To compare the design pages with the demo by eye, run node tools/hugo-dev/side-by-side.mjs after a build. It writes tools/hugo-dev/out/side-by-side/index.html. tools/hugo-dev/hugo-dev.sh screenshots rebuilds the two listing images, hugo/theme/images/screenshot.png (1500 by 1000) and tn.png (900 by 600), from the demo home page in Paper.
tools/publish-hugo.sh <version> pushes a release to the public repository: the tag first, then main. Hugo Modules resolve the semantic version tag, so there is no branch to move. Only an operator runs it; see the header of the script.
You need Docker and Node 20 or later. The script starts Ghost 6 (the ghost:6 image, SQLite) with ghost/ mounted read-only as the theme readerly, creates the admin, activates the theme and loads the Marginalia demo. Ghost listens on the first free port from 2380 (set PORT to fix it) and the script remembers the port in tools/ghost-dev/.state. The admin login is admin@readerly.test with the password in tools/ghost-dev/seed.mjs.
tools/ghost-dev/ghost-dev.sh up # start, set up, activate the theme, seed
tools/ghost-dev/ghost-dev.sh seed # reload the demo content
tools/ghost-dev/ghost-dev.sh gscan # GScan for Ghost 6 on ghost/; or: gscan dist/readerly-ghost-1.0.0.zip -z
tools/ghost-dev/ghost-dev.sh check # markup parity, browser checks, side-by-side screenshots
tools/ghost-dev/ghost-dev.sh export site/ https://readerly-ghost.listofbooks.net # static copy, verified in a browser
tools/ghost-dev/ghost-dev.sh url # print the site URL
tools/ghost-dev/ghost-dev.sh down # stop, keep the data
tools/ghost-dev/ghost-dev.sh clean # remove the container and its datagscan runs the GScan that ships in the ghost:6 image and exits with 1 on any error or warning. Recommendations do not fail it.
Editing a template needs down and up again, because Ghost reads templates at start. To mount another theme folder, set THEME_DIR.
seed.mjs loads the demo through the Admin API. It first deletes every post, page and tag, so a rerun gives the same slugs and the same HTML. It reuses the images it uploaded before, because Ghost cannot delete an upload and would rename a repeat to name-2.svg. The content comes from design/demo and design/:
- Ten reviews are posts. The newest, The Salt Orchard, is featured. A review's
excerptis the post'scustom_excerpt; a post'sleadis not loaded, because Ghost has one summary field and the theme prints it under the title and on the cards. - Facts about a book are internal tags in the order genre, other public tags,
#by:,#series:,#rating:,#pages:,#published:, then the status (#read,#reading,#want-to-read,#did-not-finish). The tag table is in the theme README. - Books on the reading log with no review are pages with the same fact tags, plus
#on-page:for a book in progress. Isobel Thorne's four novels are pages tagged#bookand#buy:. - Design markup that Ghost's editor would flatten (the verdict, the pull quote, the praise and events lists, the where-to-buy block) goes in as HTML cards.
- The site settings, navigation, accent colour, Nora Vale's profile and the theme's custom settings are set too. The seed prints any theme setting the theme does not define.
check runs three things:
- Markup parity. Each of the seven design pages and its Ghost page reduce to a tree of tag names, classes, roles and ARIA attributes, and the trees must match.
tools/ghost-dev/parity-exceptions.jsonlists the elements removed from either side first, each with a reason. The algorithm istools/lib/markup-tree.mjs. tools/wp-dev/check-pages.cjson the pages intools/ghost-dev/pages.json, at 1280 px and 390 px, in Paper and Lamplight. Requests tocdn.jsdelivr.net/ghost/, where Ghost loads Portal and its search from, are allowed; any other third-party request fails.tools/ghost-dev/side-by-side.mjsscreenshots each design page next to the Ghost page. Opentools/ghost-dev/out/side-by-side/index.html.
export crawls the sitemaps, the home page, the feed, the 404 page and everything they reference into a folder you can host on Cloudflare Pages. It rewrites the Ghost address to the public one. It removes Portal, the comments and the member-attribution scripts, and the comments section. It turns each form[data-members-form] into data-demo-form, which the theme script confirms in place. Search keeps working: sodo-search reads three files, /ghost/api/content/search-index/posts/, .../authors/ and .../tags/, and the export saves them. It writes _headers, which allows framing by ghost.org for the Marketplace preview, and _redirects when Ghost redirected something while crawling. The export then serves the copy, loads every page in a browser and fails on a request to the Ghost address, a failed request, or a search for "Salt" that finds nothing.
tools/publish-ghost-demo.sh runs all of that and deploys the copy with wrangler pages deploy. It changes a public site, so only an operator runs it, by hand.
The ghost job builds the zip (tools/build-ghost-zip.sh, which writes dist/readerly-ghost-<version>.zip), runs GScan on it, starts Ghost with the unzipped theme, seeds it and runs check. A CI job cannot reach ports published on the host, so it sets GHOST_NETWORK: Ghost joins that Docker network as ghost, and the seed and the checks run in a Playwright container on the same network.
tools/build-zip.shThis writes dist/readerly-<version>.zip, holding wordpress/ as readerly/. Upload it under Appearance > Themes > Add New. To prove it installs on a fresh site:
tools/wp-dev/wp-dev.sh zip-test dist/readerly-1.0.0.zipThe footer keeps one link, "Theme by List of Books", to https://www.listofbooks.net/. In WordPress, a site owner can edit or delete it in the Site Editor. In Hugo, a site owner removes it by adding an empty layouts/_partials/credit.html. The Ghost theme prints it next to "Published with Ghost" from ghost/partials/site/credit.hbs, which a site owner edits in the theme files.