Ship the theme's assets with the site instead of fetching them - #5
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The shared template fetched its own assets by absolute URL from elsewhere:
So every documentation site built with this action depended on
CL-web-componentspublishing to S3, and oncaltechlibrary.github.ioactingas an asset host. Nobody agreed to either arrangement and nothing tested them.
The S3 copies were thirteen months stale — reporting
0.0.12against aproject that was at
0.0.16.None of the three belonged where it was
code-blocks.cssstylespreand the copy button on documentation pages.copyToClipboard.jscreates that button. It is not a web component — nocustomElements.define, not exported from its project’smod.js.site.cssstyles: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/cssandpandoc/js, andbuild-pandoccopies them intoevery site it builds.
footer-global.jsand the Caltech Library logo keep theirCDN URLs, because sites outside this build system embed them.
Customizing: add, do not replace
--extra-cssand--extra-jsship a project’s own files and load them afterthe 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.
--templatestill opts a project out entirely, which is the honest escape hatchfor wanting different page structure.
--site-basePrefixes the asset URLs. Defaults to
/<repo>/, where GitHub Pages puts aproject site;
/for a site at a domain root.The default lives in
action.yml, not the script.bin/build-pandoc.shpromises in its own header to read no CI environment, so it must not touch
GITHUB_REPOSITORY. Run by hand with no--site-baseit emits relative URLs andthe output opens straight from disk — which is the local-preview case.
Verified by running it
--site-basehref="css/site.css"— opens from disk--site-base /CL-web-components/href="/CL-web-components/css/site.css"--site-base /with extras/css/local.cssand/js/local.js, both shipped--extra-cssfileno such file, exit 1Also run locally:
shellcheck --severity=styleclean, and the README-documents-every-input check passes for all six actions.
Follow-on
it currently hosts. It will be the first user of
site-base: /.and deleting its copies of these files.
here does not fix it, and it now has one clear owner.
Until those land, both repositories keep their copies. This repository is
canonical from now on.