juancobo · Nov 1, 2026 · Nov 1, 2026 · Nov 1, 2026 · Nov 1, 2026 · Nov 1, 2026
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
@@ -1,53 +1,47 @@
-name: Deploy Jekyll site to Pages
+name: Build and deploy Telar with Hugo
 
 on:
   push:
-    branches: ["main"]
+    branches: [main]
+  pull_request:
   workflow_dispatch:
 
 permissions:
   contents: read
-  pages: write
-  id-token: write
 
 concurrency:
-  group: "pages"
-  cancel-in-progress: false
+  group: pages-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Ruby
-        uses: ruby/setup-ruby@v1
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
-          ruby-version: '3.1'
-          bundler-cache: true
-
-      - name: Setup Pages
-        id: pages
-        uses: actions/configure-pages@v4
-
-      - name: Build with Jekyll
-        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
-        env:
-          JEKYLL_ENV: production
-
-      - name: Build search index with Pagefind
-        run: npx -y pagefind --site _site
-
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+          node-version: '22'
+          cache: npm
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: npm ci
+      - run: npm run build
+      - run: npm test
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: public
 
   deploy:
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build
     steps:
       - name: Deploy to GitHub Pages
         id: deployment

diff --git a/.gitignore b/.gitignore
@@ -1,28 +1,8 @@
-# Jekyll build files
-_site/
-.jekyll-cache/
-.jekyll-metadata
-.sass-cache/
-
-# Ruby/Bundler
-vendor/
-.bundle/
-Gemfile.lock
-
-# macOS
+node_modules/
+public/
+resources/
+.hugo_build.lock
 .DS_Store
-
-# IDEs
-.vscode/
-.idea/
-*.swp
-*.swo
-*~
-
-# Logs
 *.log
-
-# Screenshot automation
-screenshots/google-auth.json
-screenshots/gifs/_tmp_video/
-screenshots/gifs/_tmp_frames/
+reports/
+.build-result.json
diff --git a/.nojekyll b/.nojekyll
diff --git a/Gemfile b/Gemfile
diff --git a/MIGRATION.md b/MIGRATION.md
@@ -0,0 +1,52 @@
+# Jekyll → Hugo migration
+
+Pre-publication validation recorded 1 November 2026 on `site/hugo-migration`. This document records the migration scope, local checks and publication checklist.
+
+## Scope
+
+The migration starts from the approved redesigned Jekyll working tree, including its uncommitted changes, rebased onto main at `143fc62`, including its v1.8.3 release notes. Its original checkout and a separate source/rendered snapshot were preserved.
+
+All 234 existing HTML routes are retained. The native site contains 233 non-homepage pages plus English and Spanish homepages. These include all 160 canonical documentation pages, the 118-route legacy inventory, showcase pages/forms, the workshop and worksheet redirects, and the internal manual review page. The latter remains available but is excluded from search and marked noindex.
+
+The approved design, credits, screenshots, animations, video integration and copy are retained. The Spanish title is **Planea el recorrido de la historia**, with its former anchor preserved. The native Spanish homepage is `/es/`; old `?lang=` links forward while preserving the section fragment.
+
+## Native implementation
+
+Content is authored in Hugo's English and Spanish directories. Existing published URLs are explicit in front matter, and `translationKey` supplies native pairing. Shared data controls editorial navigation order, labels and media; the duplicate per-page title/translation registry is removed.
+
+The three shared page shells use native Go templates. Includes for diagrams, media, callouts and repeated guide content use shortcodes. Interactive configuration tools and showcase browser code are retained as source components. No Jekyll-generated page body is embedded in the site. The former Ruby/theme/Sass build has been removed from this worktree.
+
+Metadata, canonicals, language alternates, sitemaps and robots rules are generated by Hugo. Local builds use a separate preview configuration. Search indexes all 160 guide pages in two languages. The build uses pinned Hugo Extended 0.160.1 and Pagefind 1.5.2 dependencies installed by `npm ci`, without referencing another repository's tools.
+
+The production service addresses remain the existing showcase Worker. Local integration testing uses a separate Worker copy, database and test Turnstile keys, with no Slack destination. The documented preview harness was started successfully against the separate Worker checkout.
+
+## Validation
+
+- Clean `npm ci` succeeded.
+- Production: **20,441 checks; zero failures**.
+- Preview: **20,370 checks; zero failures**.
+- Source-to-output comparison: all 233 non-homepage pages and 160 canonical docs; **zero outstanding differences** under the recorded comparison rules.
+- Every existing served HTML route and all 118 legacy inventory entries remain available. Internal links, fragments, heading aliases, image targets and alt attributes pass.
+- Browser testing covered language pairing, both searches, slash/Escape search navigation, the configuration tools, math rendering, the gallery and both forms. English and Spanish teaching requests and one showcase request were stored locally. The three local notification jobs had zero delivery attempts and no sent timestamp.
+- Seven representative pages were measured at 390×844 and four at 768×1024. None had page-level horizontal overflow. The viewport capability affects the selected browser tab, which was explicitly verified before recording these results.
+- `git diff --check` passed. The prepared GitHub workflow has not yet run on GitHub.
+
+Machine-readable inventory and evidence are in `migration/`. Fresh test results are written to the ignored `reports/` directory. Route/content contracts are snapshots for regression checking; they are not runtime dependencies or copied page bodies.
+
+## Rendering and tool corrections
+
+The port preserves Kramdown heading IDs explicitly, converts callout annotations, supplies Chroma styles for native highlighting, and renders the approved HTML in quick-guide data as HTML. Large interactive HTML forms use native source components so CommonMark does not reinterpret their indentation as code.
+
+Two existing configuration-tool bugs were corrected during browser testing: the generator quoted its version/date twice, producing invalid YAML; and the validator did not recognise the existing `trama` theme. The generator now emits valid quoted values and the validator accepts all five installed theme names. No surrounding instructional wording was rewritten.
+
+One precisely recorded prose comparison exception covers stray visible Markdown delimiters around the Spanish “View full site” troubleshooting label. Hugo formats the unchanged words correctly. This is a rendering correction, not a new translation.
+
+## Publication checklist
+
+1. Review the complete local site at port 4004. The remaining Spanish editorial batches remain separate from this technical migration.
+2. Commit and push the migration branch when ready, then run the prepared pull-request build on GitHub. Remote CI and production deployment have not been exercised here.
+3. After the review and checks, merge to switch the existing Pages build to Hugo. No DNS or hosting migration is needed for the proposed workflow.
+4. Verify the live language homepages, old workshop links, search, gallery, Vimeo and both forms. Any live notification test should be deliberate; this migration's tests did not send notices.
+5. For rollback, restore the pre-release source/workflow commit or redeploy the previous Pages artifact. The old Jekyll working tree remains available locally for comparison.
+
+Telar exhibition sites and the Compositor's application build are unchanged by this documentation-site migration.
diff --git a/README.md b/README.md
@@ -1,94 +1,58 @@
-# Telar Documentation
+# Telar project website
 
-Official documentation site for [Telar](https://github.com/UCSB-AMPLab/telar), a minimal-computing framework that weaves together IIIF images, audio, video, and texts to create layered visual narratives for digital scholarship, public exhibitions, community storytelling, and classroom projects.
+The bilingual documentation and project website for [Telar](https://telar.org), built with Hugo Extended and Pagefind. This repository publishes the manuals, exhibition-planning guides, teaching resources, showcase and landing pages. Telar exhibitions themselves still use the separate Telar framework and its Jekyll build.
 
-## About
+## Install and preview
 
-This is a bilingual (English/Spanish) documentation site built with Jekyll using a custom docs theme with [Pagefind](https://pagefind.app/) search.
+Requires Node.js 22 or later. Regression checks additionally use Python 3, with no Python packages required.
 
-## Local Development
-
-### Prerequisites
-
-- Ruby 3.0+
-- Bundler
-- Node.js (for Pagefind search indexing)
-
-### Basic Setup (without search)
-
-```bash
-# Install dependencies
-bundle install
-
-# Serve locally with live reload
-bundle exec jekyll serve --livereload
-
-# View at http://localhost:4000
+```sh
+npm ci
+npm run build:preview
+npm run preview
 ```
 
-### With Search
+Open <http://127.0.0.1:4004/> for English, <http://127.0.0.1:4004/es/> for Spanish, or `/docs/` and `/guia/` for the guides. Existing `?lang=en` and `?lang=es` homepage links forward to the appropriate language's canonical homepage.
 
-Pagefind requires a two-step process (can't use `jekyll serve` as it overwrites the search index):
+For live content/layout rebuilding, run `npm run dev` after the initial preview build. Rebuild with `npm run build:preview` after content changes when checking search results: Pagefind indexes the generated HTML.
 
-```bash
-# Build Jekyll site
-bundle exec jekyll build
+### Previewing forms and the showcase
 
-# Build search index and serve
-npx pagefind --site _site --serve
+The production site uses the separate `telar-showcase` Cloudflare Worker. The local preview points both forms and the gallery to port 8790 instead. To run the local integration harness, use a checkout of that Worker containing the teaching-request endpoint and its installed dependencies:
 
-# View at http://localhost:1414
+```sh
+node scripts/preview-api.mjs --worker /path/to/telar-showcase
 ```
 
-For regular development without search, use `jekyll serve`. Search is automatically built during GitHub Actions deployment.
-
-## Bilingual Structure
+The harness copies only Worker source and migrations into a temporary directory, creates a separate local database, loads a public showcase fixture and uses Cloudflare's test Turnstile keys. It does not copy credentials, notification destinations or existing records. Submitted test data remains in that temporary database; Slack delivery is disabled. Stop the API with Ctrl-C. The temporary path is printed at startup.
 
-This site uses a manual bilingual approach without plugins:
+The pages can be browsed without this API. Forms then show their existing connection error; the gallery shows its existing fallback. Production service configuration is in `hugo.json`, and local overrides are in `hugo.preview.json`.
 
-- **English pages**: Standard `.md` files (e.g., `docs/1-getting-started.md`)
-- **Spanish pages**: `.es.md` extension (e.g., `docs/1-getting-started.es.md`)
-- **URL structure**:
-  - English: `/`, `/about/`, `/docs/...`
-  - Spanish: `/es/`, `/acerca-de/`, `/documentacion/...`
+## Edit the site
 
-### Adding Content
+- `content/en/` and `content/es/` contain the content. Paths mirror the published routes. An `_index.md` is a page that also has child pages.
+- Each page's `url` retains its published address. Keep its `translationKey` aligned with its counterpart; Hugo supplies the translation links.
+- `data/guides.json` contains shared guide/quick-guide copy. `data/docs_navigation.json` controls the editorial grouping and order. Page titles and translation pairing live in front matter rather than a second page registry.
+- `data/teaching_contact.json` contains the approved teaching form copy. `data/docs_media.json` supplies screenshot captions and optional animations.
+- `layouts/_partials/docs-shell.html`, `section-shell.html` and `home.html` are the three shared page shells. Metadata lives in `meta.html`.
+- `layouts/_shortcodes/` contains media, callout, diagram and shared-content components. Larger interactive tools use source templates in `layouts/_partials/pages/`.
+- `static/` contains the existing styles, browser scripts and media. Hugo does not rewrite Telar framework examples in the documentation.
 
-1. Create English page: `docs/new-page.md`
-2. Add frontmatter with `lang: en` and `permalink:`
-3. Create Spanish version: `docs/new-page.es.md`
-4. Add frontmatter with `lang: es` and Spanish `permalink:`
+Preserve explicit heading IDs and alias spans when changing headings. They keep existing links and workshop references working. The approved design and wording carry over; the remaining Spanish editorial review is a separate task.
 
-### Navigation
+## Build and verify
 
-The custom navigation (`_includes/components/site_nav.html`) groups pages by language, showing:
-- English section with English pages
-- Español section with Spanish pages
-
-The language switcher appears at the top-right of each page.
-
-## Customization
-
-- **Theme styles**: `_sass/custom/custom.scss`
-- **Logo**: `images/telar.png` (placeholder - replace with final logo)
-- **Site config**: `_config.yml`
-
-## Credits
-
-Telar is developed by Adelaida Ávila, Ana María Cárdenas Gasca, Juan Cobo Betancourt, Natalie Cobo, Santiago Muñoz, and students and scholars at the [UCSB Archives, Memory, and Preservation Lab](https://ampl.clair.ucsb.edu), the UT Archives, Mapping, and Pedagogy Lab, and [Neogranadina](https://neogranadina.org).
+```sh
+npm run build
+npm test
+```
 
-We gratefully acknowledge the support of the [Caribbean Digital Scholarship Collective](https://cdscollective.org), the [Center for Innovative Teaching, Research, and Learning (CITRAL)](https://citral.ucsb.edu/home) at the University of California, Santa Barbara, the [UCSB Library](https://library.ucsb.edu), the [Routes of Enslavement in the Americas University of California MRPI](https://www.humanities.uci.edu/routes-enslavement-americas), and the [Department of History of The University of Texas at Austin](https://liberalarts.utexas.edu/history/).
+The production build writes `public/` and indexes the guides in English and Spanish. The test command checks the migrated route inventory, legacy anchors, headings, code examples, tables, callouts, images, metadata, translation links and internal link targets. It also rejects prototype dependencies and local runtime URLs in production HTML. Results are written to the ignored `reports/` directory.
 
-Telar is built with:
-- [Jekyll](https://jekyllrb.com/) - Static site generator
-- [OpenSeadragon](https://openseadragon.github.io/) - IIIF viewer
-- [Bootstrap 5](https://getbootstrap.com/) - CSS framework
-- [libvips](https://www.libvips.org/) - IIIF tile generator
+After an approved change to a heading or code example, update that page's entry in `migration/content-contracts.json` as part of the same edit. Retain the old anchor IDs as aliases. Ordinary prose changes do not require changing the heading/code contracts.
 
-It is based on [Paisajes Coloniales](https://paisajescoloniales.com/), and inspired by:
-- [Wax](https://minicomp.github.io/wax/) - Minimal computing for digital exhibitions
-- [CollectionBuilder](https://collectionbuilder.github.io/) - Static digital collections
+`migration/inventory.json` records the original source file and native Hugo destination for each migrated page. `migration/content-contracts.json` records the baseline rendering contracts. These are regression evidence, not generated page bodies.
 
-## License
+The Pages workflow builds and tests pull requests. Its deployment job runs only for `main`, after the checks pass. The deployment artifact is `public/`; source files, local fixtures and migration records are not published.
 
-The Telar documentation site is licensed under the [Creative Commons Attribution 4.0 International License (CC BY 4.0)](LICENSE). You are free to share and adapt the content, including for commercial use, as long as you give appropriate credit and indicate if changes were made.
+See [MIGRATION.md](MIGRATION.md) for migration scope, validation and the remaining release steps.
diff --git a/_config.dev.yml b/_config.dev.yml