Skip to content

Ship the theme's assets with the site instead of fetching them - #5

Merged
t4k merged 1 commit into
mainfrom
theme/ship-assets-with-the-site
Sep 2, 2026
Merged

Ship the theme's assets with the site instead of fetching them#5
t4k merged 1 commit into
mainfrom
theme/ship-assets-with-the-site

Conversation

@t4k

@t4k t4k commented Sep 2, 2026

Copy link
Copy Markdown
Member

The shared template fetched its own assets by absolute URL from elsewhere:

<link rel="stylesheet" href="https://caltechlibrary.github.io/css/site.css">
<link rel="stylesheet" href="https://media.library.caltech.edu/cl-webcomponents/css/code-blocks.css">
<script type="module" src="https://media.library.caltech.edu/cl-webcomponents/copyToClipboard.js"></script>

So every documentation site built with this action depended on
CL-web-components publishing to S3, and on caltechlibrary.github.io acting
as an asset host. Nobody agreed to either arrangement and nothing tested them.
The S3 copies were thirteen months stale — reporting 0.0.12 against a
project that was at 0.0.16.

None of the three belonged where it was

  • code-blocks.css styles pre and the copy button on documentation pages.
  • copyToClipboard.js creates that button. It is not a web component — no
    customElements.define, not exported from its project’s mod.js.
  • site.css styles :root, body, header, nav, section, aside
    exactly the structure this template emits. It is the theme’s stylesheet, and
    the organization site was its first consumer rather than its owner.

They move to pandoc/css and pandoc/js, and build-pandoc copies them into
every site it builds. footer-global.js and the Caltech Library logo keep their
CDN URLs, because sites outside this build system embed them.

Customizing: add, do not replace

--extra-css and --extra-js ship a project’s own files and load them after
the theme’s. For CSS that is enough to override anything, because later rules
win — so no project needs a copy of a theme file, and therefore no project can
hold a stale one. ADR-0008 records why overlay-by-filename was rejected: it puts
an editable, committed copy of a theme file in each repository, which is the
failure this repository exists to prevent.

--template still opts a project out entirely, which is the honest escape hatch
for wanting different page structure.

--site-base

Prefixes the asset URLs. Defaults to /<repo>/, where GitHub Pages puts a
project site; / for a site at a domain root.

The default lives in action.yml, not the script. bin/build-pandoc.sh
promises in its own header to read no CI environment, so it must not touch
GITHUB_REPOSITORY. Run by hand with no --site-base it emits relative URLs and
the output opens straight from disk — which is the local-preview case.

Verified by running it

Case Result
no --site-base href="css/site.css" — opens from disk
--site-base /CL-web-components/ href="/CL-web-components/css/site.css"
--site-base / with extras theme first, then /css/local.css and /js/local.js, both shipped
missing --extra-css file no such file, exit 1

Also run locally: shellcheck --severity=style clean, and the README-documents-
every-input check passes for all six actions.

Follow-on

Until those land, both repositories keep their copies. This repository is
canonical from now on.

The shared template fetched site.css, code-blocks.css and copyToClipboard.js
by absolute URL, so every site built with this action depended on
CL-web-components publishing to S3 and on caltechlibrary.github.io acting as
an asset host. Nobody agreed to either arrangement and nothing tested them.
The S3 copies were thirteen months stale, reporting 0.0.12 against a project
at 0.0.16.

None of the three belonged where it was. code-blocks.css styles pre and the
copy button on documentation pages; copyToClipboard.js creates that button and
is not a web component at all; site.css styles :root, body, header, nav,
section and aside, which is exactly the structure this template emits. They
are this theme's files, and the projects holding them were consumers.

They now live in pandoc/css and pandoc/js, and build-pandoc copies them into
every site it builds. footer-global.js and the Caltech Library logo keep their
CDN URLs, because sites outside this build system embed them.

Projects customize by adding, not replacing: --extra-css and --extra-js ship a
project's own files and load them after the theme's, and for CSS that is
enough to override anything, because later rules win. No project needs a copy
of a theme file, so no project can hold a stale one.

--site-base prefixes the asset URLs, defaulting to /<repo>/ where Pages puts a
project site. The default is set by the action, not the script, so the script
keeps knowing nothing about CI -- run by hand with no --site-base it emits
relative URLs and the output opens from disk.

ADR-0008 records the decision and the three rejected alternatives.
@t4k
t4k merged commit 1a53ab9 into main Sep 2, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant