Render the docs site instead of publishing the repository - #46
Merged
Conversation
static.yml uploads the entire repository as the Pages artifact (`path: '.'`). Two consequences, both live right now: - Repository internals are served publicly. Makefile, codemeta.json, deno.json and page.tmpl all return 200 from software.library.caltech.edu/CL-web-components/. - The site is whatever HTML happens to be committed. Nothing renders the Markdown, so a documentation change only reaches the site if someone remembers to run `make website` and commit the output. This replaces it with a build. The build logic is not copied into this repository: it lives in caltechlibrary/workflows and is referenced at @v1, so a fix there reaches this site -- and every other Caltech Library site -- on the next run, with nothing written back here. Sources move into docs/, which is what makes the rest possible: the build no longer looks at the repository root, so the generated HTML committed there becomes unused and can be removed separately rather than as part of this change. Demo and test pages move with them; they are sources, not output. README.md and INSTALL.md stay in the root because cmt writes them there and can only write to the root -- its generator registry keys on the exact output filename, so `cmt codemeta.json docs/about.md` exits with "unsupported format". `extra-sources: "*.md"` renders them, so every Markdown file that is published today is still published. The Pandoc Lua filters are no longer carried here; both are byte-identical to the shared copies. page.tmpl stays, moved to pandoc/ and passed as an override, because its nav is specific to this project. deno.json now bundles into dist/ rather than over the top of the repository root, so the workflow publishes freshly built bundles rather than whatever was last committed. The `release` task was already doing this and had drifted from `build`, which is why release zips and local builds could disagree. website.mak and website.ps1 are deleted; nothing reads them once the build is in CI, and leaving them invites someone to run a build that writes HTML back into the working tree. No search index is built. search.md and pagefind/ were removed and the Search link is commented out of the nav, so there is no page to index. Adding search back is a separate decision. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
search.md and pagefind/ were removed and the Search nav link commented out,
but the generated search.html stayed committed -- so the live site serves a
search page whose assets 404:
search.html 200
pagefind/pagefind-ui.js 404
pagefind/pagefind.js 404
The page loads and silently does nothing.
The index is rebuilt on every run now rather than committed, so it cannot go
stale the way the old one did. search.md returns to docs/ unchanged, including
the two behaviours worth keeping: baseUrl computed from the path, so results
resolve under a project-pages prefix, and ?q= deep-linking via triggerSearch.
The shared action pins Pagefind 1.5.2, which is the current release. The
accessibility improvements people associate with 1.5.0 come from its new
Component UI, which the release notes are explicit is optional -- the Default
UI "remains available and supported" at this version. Migrating to the
Component UI is worth doing but is a separate change, and worth doing once in
the shared repository rather than in each site: this search page is
byte-identical across CL-web-components, CL-Pandoc-filters and etd-workflow,
and near-identical in several more.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
t4k
added a commit
to t4k/CL-web-components
that referenced
this pull request
Sep 1, 2026
Adopting the MADR format already used in caltechlibrary/alchemist and caltechlibrary/workflows: docs/decisions/, NNNN-kebab-case.md, immutable once accepted, rejected options recorded. Two decisions, chosen on the test in ADR-0001 -- a decision worth recording is one whose result looks like unnecessary complication to someone who did not watch it being made, and which a future reader would therefore be tempted to "simplify" back: 0002 build the site rather than publishing the repository 0003 keep sources and generated files in separate namespaces Both carry the alternatives that were rejected and why, which is the part the code cannot show. 0002 records that a self-contained workflow was built first and worked, and was rejected anyway because it is a copy -- and that the reusable workflow cannot be used here, since a caller cannot add a Deno setup step to a job it did not write. 0003 records why several Markdown files stay in the root: cmt writes them there and its generator registry keys on the exact output filename, so it cannot write to docs/. The reasoning was in the description of caltechlibrary#46, which stops being read the moment it merges. The ADRs are not rendered into the site: the build globs docs/*.md without recursing, so docs/decisions/ is carried in the repository and read on GitHub. That suits the audience -- they are for people changing this repository, not for people using the components. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This was referenced Sep 1, 2026
t4k
added a commit
that referenced
this pull request
Sep 2, 2026
The 28 committed HTML files became orphaned when #46 moved the docs build to assemble from docs/ rather than filtering the repository root. Nothing reads them: no kept file links to any of them, and the build globs only Markdown. Both pages that matter are generated -- README.md becomes index.html via build-pandoc's --index-from default, and docs/search.md becomes search.html. make.ps1 goes with website.ps1 and website.mak, already removed. .nojekyll was for branch-based Pages; deployment is artifact-based now, so Jekyll never runs. INSTALL_NOTES_macOS.md and INSTALL_NOTES_Windows.md document bypassing Gatekeeper and SmartScreen for unsigned executables. This repository ships browser JavaScript and has no executables. cmt already excludes both from --init for deno-webcomponent projects, so removing them applies its design rather than diverging from it. Also drops the PowerShell block in docs/building_web_components_with_deno.md, which invoked the deleted make.ps1.
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
1 participant
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.
static.ymluploads the entire repository as the Pages artifact (path: '.'). This replaces it with an actual build.Three problems it fixes, all live right now
Repository internals are served publicly. All of these return 200 from
software.library.caltech.edu/CL-web-components/today:The site is whatever HTML happens to be committed, and it has already drifted. Commit 7f20bdd updated the hostname in
INSTALL.mdandREADME.md, but the committed HTML was never regenerated — so the live pages still saycaltechlibrary.github.io:Search is broken.
search.mdandpagefind/were removed but the generatedsearch.htmlstayed committed, so the page loads and silently does nothing:Rendering from source fixes all three without anyone having to remember anything.
What changed
@v1, so a fix there reaches this site — and every other Caltech Library site — on the next run, with nothing written back here.docs/. Demo and test pages move with them; they are sources, not output.search.mdreturns unchanged, the index is rebuilt every run rather than committed, and the nav link is uncommented.pandoc/page.tmplis kept and passed as an override, because its nav is specific to this project.deno.jsonbundles intodist/rather than over the repository root, so the site gets freshly built bundles rather than whatever was last committed. (releasewas already doing this and had drifted frombuild.)static.yml,website.mak,website.ps1deleted.Verified against what is published today
The built site was compared page-by-page with the HTML currently committed:
DEPLOYMENT.mdINSTALL.html,index.html(the hostname above)search.html, now with a working index (41 pages)about.htmlOn
about.html:about.mdwas deleted but its generated HTML is still committed, so the site serves a page with no source. It is already commented out of the nav. This stops publishing it. If it should come back, the fix is to restore the Markdown — say the word.Every other asset is unchanged: bundles,
mod.js,LICENSE,css/,src/.Reviewer notes
static.ymlalready uses it. The custom domain is a repository setting with noCNAMEfile, so artifact deploys do not disturb it.README.mdandINSTALL.mdstay in the root becausecmtwrites them there and can only write to the root — its generator registry keys on the exact output filename, socmt codemeta.json docs/about.mdexits withunsupported format.extra-sources: "*.md"renders them, so nothing published today stops being published.docs-pandoc.ymlreusable workflow, because the site publishes compiled bundles and a reusable workflow gives the caller nowhere to add a Deno setup step.docs/means the generated HTML still committed in the root is now unused by the build. Removing it is a separate, purely subtractive change.🤖 Generated with Claude Code