caltechlibrary · t4k · Sep 1, 2026 · Sep 1, 2026 · Sep 1, 2026
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,81 @@
+name: Docs
+
+# Builds the documentation site and publishes it to GitHub Pages.
+#
+# Replaces static.yml, which uploaded the entire repository as the site. That
+# published the Makefile, codemeta.json, deno.json, page.tmpl and everything
+# else in the root -- all of them fetchable from software.library.caltech.edu
+# today -- and it served whatever HTML happened to be committed rather than
+# rendering the Markdown.
+#
+# The build itself lives in caltechlibrary/workflows, so a fix there reaches
+# this site -- and every other Caltech Library site -- on the next run, with
+# nothing written back into this repository.
+#
+# This calls the build action rather than the docs-pandoc.yml reusable
+# workflow, because the site publishes compiled component bundles and a
+# reusable workflow gives the caller nowhere to add a Deno setup step.
+#
+# The Pandoc Lua filters come from the shared repository; both are identical to
+# the copies that used to live in this root.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: denoland/setup-deno@v2
+        with:
+          deno-version: v2.x
+
+      - name: Bundle components
+        run: deno task build
+
+      - uses: caltechlibrary/workflows/.github/actions/build-pandoc@v1
+        with:
+          docs-dir: docs
+          # Markdown in the root is published too. cmt writes README.md and
+          # INSTALL.md there and can only write to the root.
+          extra-sources: "*.md"
+          template: pandoc/page.tmpl
+          include: |
+            dist/*.js
+            mod.js
+            LICENSE
+            css
+            src
+
+      # Pagefind is pinned in the shared action. 1.5.2 is current; the
+      # accessibility improvements in 1.5.0 come from its new Component UI,
+      # which is a separate migration and does not require a version change.
+      - uses: caltechlibrary/workflows/.github/actions/index-site@v1
+
+      - uses: caltechlibrary/workflows/.github/actions/deploy-site@v1
+
+  deploy:
+    needs: build
+    # Pull requests build but do not publish.
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5
diff --git a/.github/workflows/static.yml b/.github/workflows/static.yml
diff --git a/.gitignore b/.gitignore
@@ -9,6 +9,9 @@ bin/
 dist/
 scratch/
 
+# The site is assembled by CI and uploaded as an artifact, never committed.
+/_site/
+
 # macOS system files
 .DS_Store
 

diff --git a/add-col-scope.lua b/add-col-scope.lua
diff --git a/deno.json b/deno.json
@@ -1,6 +1,6 @@
 {
   "tasks": {
-    "build": "deno bundle --platform browser --outdir=./ src/*.js ; deno bundle --platform browser mod.js --output=cl-web-components.js",
+    "build": "deno bundle --platform browser --outdir=./dist src/*.js ; deno bundle --platform browser --output=dist/cl-web-components.js mod.js",
    "release": "deno bundle --platform=browser --outdir=./dist src/*.js ; deno bundle --platform=browser --output=dist/cl-web-components.js mod.js"
   },
   "imports": {

diff --git a/DEPLOYMENT.md → docs/DEPLOYMENT.md b/DEPLOYMENT.md → docs/DEPLOYMENT.md
@@ -25,54 +25,42 @@ This file is included in gitignore and is **not committed to git**.
 
 Use this workflow when **only documentation (`.md`) files have changed**.
 
-## Step 1. Convert mardown files to html files
+## Step 1. Edit and push
 
-```bash
-make website
-```
-
-This command:
-
-- Converts all `*.md` files to `*.html` using **Pandoc**
-- Rebuilds the **Pagefind search index**
-
-## Step 2. Save and push your working branch
-
-If you added **new files**, stage them first:
+Documentation sources live in `docs/`. Edit the Markdown, then commit and push:
 
 ```bash
 git add <filename>
+git commit -m "your commit message"
+git push
 ```
 
-Then commit and push:
+There is no HTML to build by hand. The **Docs** workflow renders the site with
+Pandoc and publishes it to GitHub Pages on every push to `main`. The build
+lives in [caltechlibrary/workflows](https://github.com/caltechlibrary/workflows),
+so a fix there reaches this site on the next run. The Pandoc template is this
+repository's own, in `pandoc/`; the Lua filters come from the shared repository.
 
-```bash
-make save msg="your commit message"
-```
-
-`make save` uses `git commit -am` which only commits already-tracked files. New files must be staged with `git add` first.
-
-## Step 3. Publish html files to GitHub Pages
+## Step 2. Confirm the deployment
 
 ```bash
-./publish.bash
+gh run watch
 ```
 
-This script will prompt you:
+The site updates at <https://software.library.caltech.edu/CL-web-components/>
+when the workflow completes. Pull requests build the site but do not publish
+it, so a change that breaks the docs fails in review rather than after merge.
 
-```
-You're in main branch
-You need to pull in changes to the gh-pages branch to publish
-process Y/n
-```
+### Previewing locally
 
-Enter `y` to proceed. 
+Clone the shared repository once and put its `bin/` on your `PATH`, then:
 
-It will:
+```bash
+build-pandoc.sh --docs-dir docs --extra-source "*.md" --template pandoc/page.tmpl
+open _site/index.html
+```
 
-- Merge your current branch into `gh-pages`
-- Push the update to GitHub Pages
-- Switch you back to your working branch
+That is the same script CI runs.
 
 ---
 
@@ -101,12 +89,6 @@ This command runs `deno task build` and bundles:
 
 This shows which files will be uploaded without making changes.
 
-## Step 3. Build the documentation website
-
-```bash
-make website
-```
-
 ## Step 4. Save and push your working branch
 
 If you added **new files**, stage them first:
@@ -135,21 +117,7 @@ This script:
 - Places them under `/cl-webcomponents/` in the S3 bucket
 - Creates a **CloudFront cache invalidation** so the CDN serves the new files
 
-## Step 6. Publish html files to GitHub Pages
-
-```bash
-./publish.bash
-```
-
-This script will prompt you:
-
-```
-You're in main branch
-You need to pull in changes to the gh-pages branch to publish
-process Y/n
-```
-
-Enter `y` to proceed.
+The documentation site redeploys on its own when the push lands on `main`.
 
 ---
 
@@ -241,9 +209,8 @@ https://github.com/caltechlibrary/CL-web-components/releases
 | Task | Command |
 |-----|---------|
 | Compile source code | `make build` |
-| Build documentation website | `make website` |
 | Save and push working branch | `make save msg="your message"` |
-| Publish docs to GitHub Pages | `./publish.bash` |
+| Deploy the docs site | Automatic on push to `main` |
 | Preview S3 deployment | `./publish_to_s3.bash dry-run` |
 | Deploy JS to S3 and invalidate CDN cache | `./publish_to_s3.bash` |
 | Invalidate CDN cache only | `./invalidate_cdn.bash` |

diff --git a/DEVELOPERS.md → docs/DEVELOPERS.md b/DEVELOPERS.md → docs/DEVELOPERS.md
diff --git a/building_web_components_with_deno.md → docs/building_web_components_with_deno.md b/building_web_components_with_deno.md → docs/building_web_components_with_deno.md
diff --git a/card-layout.md → docs/card-layout.md b/card-layout.md → docs/card-layout.md
diff --git a/demo_a-to-z-list_long.html → docs/demo_a-to-z-list_long.html b/demo_a-to-z-list_long.html → docs/demo_a-to-z-list_long.html
diff --git a/demo_a-to-z-list_multiple.html → docs/demo_a-to-z-list_multiple.html b/demo_a-to-z-list_multiple.html → docs/demo_a-to-z-list_multiple.html
diff --git a/demo_a-to-z-list_short.html → docs/demo_a-to-z-list_short.html b/demo_a-to-z-list_short.html → docs/demo_a-to-z-list_short.html
diff --git a/demo_agent-list.html → docs/demo_agent-list.html b/demo_agent-list.html → docs/demo_agent-list.html
diff --git a/demo_card-layout.html → docs/demo_card-layout.html b/demo_card-layout.html → docs/demo_card-layout.html
diff --git a/demo_csv0.html → docs/demo_csv0.html b/demo_csv0.html → docs/demo_csv0.html
diff --git a/demo_csv1.html → docs/demo_csv1.html b/demo_csv1.html → docs/demo_csv1.html
diff --git a/demo_csv2.html → docs/demo_csv2.html b/demo_csv2.html → docs/demo_csv2.html
diff --git a/demo_csv3.html → docs/demo_csv3.html b/demo_csv3.html → docs/demo_csv3.html
diff --git a/demo_csv4.html → docs/demo_csv4.html b/demo_csv4.html → docs/demo_csv4.html
diff --git a/demo_csv5.html → docs/demo_csv5.html b/demo_csv5.html → docs/demo_csv5.html
diff --git a/demo_csv_autocomplete0.html → docs/demo_csv_autocomplete0.html b/demo_csv_autocomplete0.html → docs/demo_csv_autocomplete0.html
diff --git a/demo_csv_autocomplete1.html → docs/demo_csv_autocomplete1.html b/demo_csv_autocomplete1.html → docs/demo_csv_autocomplete1.html
diff --git a/demo_csv_basic.html → docs/demo_csv_basic.html b/demo_csv_basic.html → docs/demo_csv_basic.html
diff --git a/demo_csv_customCleanupFilter.html → docs/demo_csv_customCleanupFilter.html b/demo_csv_customCleanupFilter.html → docs/demo_csv_customCleanupFilter.html
diff --git a/demo_csv_submit.html → docs/demo_csv_submit.html b/demo_csv_submit.html → docs/demo_csv_submit.html
diff --git a/demo_footer_global.html → docs/demo_footer_global.html b/demo_footer_global.html → docs/demo_footer_global.html
diff --git a/demo_footer_global_lite.html → docs/demo_footer_global_lite.html b/demo_footer_global_lite.html → docs/demo_footer_global_lite.html
diff --git a/demo_organization_list.html → docs/demo_organization_list.html b/demo_organization_list.html → docs/demo_organization_list.html
diff --git a/demo_people_list.html → docs/demo_people_list.html b/demo_people_list.html → docs/demo_people_list.html
diff --git a/demo_table-sortable.html → docs/demo_table-sortable.html b/demo_table-sortable.html → docs/demo_table-sortable.html
diff --git a/enhance_code_blocks.md → docs/enhance_code_blocks.md b/enhance_code_blocks.md → docs/enhance_code_blocks.md
diff --git a/footer-global.md → docs/footer-global.md b/footer-global.md → docs/footer-global.md
diff --git a/integrating_CSS_in_web_components.md → docs/integrating_CSS_in_web_components.md b/integrating_CSS_in_web_components.md → docs/integrating_CSS_in_web_components.md
diff --git a/docs/search.md b/docs/search.md
@@ -0,0 +1,30 @@
+
+
+# CL-web-components
+
+<link href="./pagefind/pagefind-ui.css" rel="stylesheet">
+<script src="./pagefind/pagefind-ui.js" type="text/javascript"></script>
+<div id="search"></div>
+<script>
+const u = URL.parse(window.location.href);
+const basePath = u.pathname.replace(/search.html$/g, '');
+
+// Function to extract query parameters from the URL
+function getQueryParam(name) {
+  const urlParams = new URLSearchParams(window.location.search);
+  return urlParams.get(name);
+}
+
+// Extract the query parameter
+const searchQuery = getQueryParam('q');
+
+window.addEventListener('DOMContentLoaded', (event) => {
+    const searchUI = new PagefindUI({ 
+            element: "#search",
+            baseUrl: basePath
+    });
+    if (searchQuery) {
+        searchUI.triggerSearch(searchQuery);
+    }
+});
+</script>
diff --git a/table-sortable.md → docs/table-sortable.md b/table-sortable.md → docs/table-sortable.md
diff --git a/textarea-agent-list-test.html → docs/textarea-agent-list-test.html b/textarea-agent-list-test.html → docs/textarea-agent-list-test.html
diff --git a/textarea-agent-list.md → docs/textarea-agent-list.md b/textarea-agent-list.md → docs/textarea-agent-list.md
diff --git a/textarea-csv.md → docs/textarea-csv.md b/textarea-csv.md → docs/textarea-csv.md
diff --git a/textarea-csv_test.html → docs/textarea-csv_test.html b/textarea-csv_test.html → docs/textarea-csv_test.html
diff --git a/ul-a-to-z-list.md → docs/ul-a-to-z-list.md b/ul-a-to-z-list.md → docs/ul-a-to-z-list.md
diff --git a/user_manual.md → docs/user_manual.md b/user_manual.md → docs/user_manual.md
diff --git a/web_component_naming.md → docs/web_component_naming.md b/web_component_naming.md → docs/web_component_naming.md
diff --git a/links-to-html.lua b/links-to-html.lua
diff --git a/page.tmpl → pandoc/page.tmpl b/page.tmpl → pandoc/page.tmpl
@@ -21,7 +21,7 @@
     <li><a href="DEPLOYMENT.html">DEPLOYMENT</a></li>
     <li><a href="user_manual.html">User Manual</a></li>
     <!-- <li><a href="about.html">About</a></li> -->
-    <!-- <li><a href="search.html">Search</a></li> -->
+    <li><a href="search.html">Search</a></li>
     <li><a href="https://github.com/caltechlibrary/CL-web-components">Code Repository</a></li>
 </ul>
 </nav>

diff --git a/website.mak b/website.mak
diff --git a/website.ps1 b/website.ps1