generate search index in CI job

Author: Frotty

.githooks/pre-commit

@@ -0,0 +1,69 @@
+name: Build and deploy site
+
+# Builds the Jekyll site, generates the Pagefind search index from the *built*
+# site, and deploys the result to GitHub Pages. Because the index is generated
+# here on every deploy, it can never drift out of sync with the content (which
+# is what happened when the index was hand-committed into the repo).
+#
+# Requires repo Settings -> Pages -> "Build and deployment" -> Source = "GitHub Actions".
+
+on:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one in-flight deploy at a time; let a running deploy finish rather than
+# cancelling it (cancelling a half-published deploy can leave Pages inconsistent).
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      JEKYLL_ENV: production
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Build site
+        run: bundle exec jekyll build
+
+      - name: Generate Pagefind search index
+        run: npx -y pagefind@1.5.2 --site _site
+
+      - name: Verify search index exists
+        run: test -f _site/pagefind/pagefind.js && test -f _site/pagefind/pagefind-entry.json
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/pages.yml

@@ -2,4 +2,9 @@
 config.codekit
 _site
 .jekyll-metadata
-_stdlib
+_stdlib
+
+# Pagefind search index is generated by CI (.github/workflows/pages.yml) on
+# every deploy. Never commit it — a hand-committed index drifts out of sync
+# with the content and breaks search.
+pagefind/

.gitignore

@@ -55,52 +55,36 @@ Adding a standard library doc page works almost the same as tutorials.
     - Change the `sections` to match the uri of the pages of your tutorial.
 * Write your new_doc pages, being sure to update the heading sections as necessary.
 
-## Building Search Index
+## Search Index
 
-The site now uses `pagefind` for fully local static search. No external API key is required.
+The site uses [`pagefind`](https://pagefind.app/) for fully local static search. No external API key is required.
 
-For GitHub Pages compatibility, the generated `pagefind/` folder is committed to this repository.
+**The index is generated automatically by CI on every deploy** — see
+[`.github/workflows/pages.yml`](.github/workflows/pages.yml). It builds the
+site, runs Pagefind against the *built* `_site`, and deploys the result to
+GitHub Pages. Because the index is rebuilt from the actual content on every
+deploy, it can never drift out of sync.
 
-1. Build the site:
+> **Do not commit a `pagefind/` folder.** It is `.gitignore`d on purpose. A
+> hand-committed index drifts from the content and breaks search (you get
+> "SEARCH INDEX NOT FOUND" on the live site). Let CI generate it.
 
-    `bundler exec jekyll build`
+### One-time GitHub setup
 
-2. Generate the search index into `_site/pagefind`:
+In repo **Settings → Pages → Build and deployment**, set **Source** to
+**"GitHub Actions"**. The workflow then publishes the site (custom domain
+`wurstlang.org` is preserved via the `CNAME` file).
 
-    `npx -y pagefind --site _site`
-
-3. Sync the generated index into tracked `pagefind/`:
-
-    `rm -rf pagefind && cp -R _site/pagefind ./pagefind`
-
-   PowerShell equivalent:
-
-    `if (Test-Path pagefind) { Remove-Item -Recurse -Force pagefind }; Copy-Item -Recurse _site/pagefind ./pagefind`
-
-4. Serve `_site` (or deploy it). Search will load from `/pagefind/pagefind.js`.
-
-Prerequisite for indexing: Node.js (for `npx pagefind`).
-
-### Pre-commit Hook For Indexing
-
-Set up repo hooks once:
-
-`git config core.hooksPath .githooks`
-
-Then every commit will:
-
-1. Build Jekyll
-2. Generate Pagefind index
-3. Sync `_site/pagefind` to tracked `pagefind/`
-4. Auto-stage `pagefind/`
-
-To bypass once:
+### Local dev with `jekyll serve`
 
-`SKIP_PAGEFIND_HOOK=1 git commit ...`
+`jekyll serve` does not generate a search index. To preview search locally:
 
-PowerShell equivalent:
+1. Build the site: `bundle exec jekyll build`
+2. Generate the index into `_site/pagefind`: `npx -y pagefind@1.5.2 --site _site`
+3. Serve `_site` (e.g. `npx -y serve _site`). Search loads from `/pagefind/pagefind.js`.
 
-`$env:SKIP_PAGEFIND_HOOK='1'; git commit ...; Remove-Item Env:SKIP_PAGEFIND_HOOK`
+Repeat steps 1–2 after content changes you want reflected in local search.
+Prerequisite: Node.js (for `npx pagefind`).
 
 ### Jenkins
 
@@ -116,17 +100,3 @@ To use it:
 1. Create a Jenkins Pipeline (or Multibranch Pipeline) job for this repository.
 2. Keep script source as `Jenkinsfile` in SCM.
 3. Ensure the Jenkins agent has Ruby/Bundler and Node.js/npm available.
-
-### Local dev with `jekyll serve`
-
-`jekyll serve` rebuilds `_site`. To keep local search working:
-
-1. Start Jekyll:
-
-    `bundler exec jekyll serve`
-
-2. In a second terminal, generate Pagefind index:
-
-    `npx -y pagefind --site _site`
-
-3. Repeat step 2 after content changes that should be searchable.

README.md

@@ -19,8 +19,6 @@ exclude:
   - assets/plugins/jquery-scrollTo/demo
   - assets/plugins/jquery-scrollTo/tests
   - assets/plugins/lightbox/examples
-keep_files:
-  - pagefind
 repository: wurstscript/wurstscript.github.io
 url: https://wurstlang.org
 baseurl: ""

_config.yml

@@ -579,6 +579,39 @@ header.branding {
     color: var(--text-color-secondary);
 }
 
+.local-search-status {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 10px 2px;
+    color: var(--text-color-secondary);
+    font-size: 14px;
+}
+
+.local-search-error {
+    color: var(--text-color);
+}
+
+.local-search-spinner {
+    flex: none;
+    width: 16px;
+    height: 16px;
+    border-radius: 50%;
+    border: 2px solid var(--divider-dark);
+    border-top-color: var(--color-primary);
+    animation: local-search-spin 0.6s linear infinite;
+}
+
+@keyframes local-search-spin {
+    to { transform: rotate(360deg); }
+}
+
+@media (prefers-reduced-motion: reduce) {
+    .local-search-spinner {
+        animation-duration: 1.6s;
+    }
+}
+
 .pagefind-meta {
     display: none !important;
 }