Declutter, ORD & Matomo Stats (#21)

* refactor(scripts): split HEI cross-check workflow

Keep the registry validation logic easier to maintain and test without changing the CLI entry point.

Exclude the Wikidata SPARQL endpoint from automated link checks because it returns transient gateway errors.

* refactor(dashboards): extract shared markup helpers

Reduce repeated institution-type, table wrapper, and download markup across the dashboard pages while keeping the rendered output unchanged.

* build(posters): share docposter extension assets

Keep poster extension resources in one project-level location so updates do not need to be copied into each poster directory.

* chore(dev): add Python quality hooks

Run formatting, linting, and type checks before commit so Python changes are validated with the same toolchain used in CI.

* fix(scripts): tolerate missing OpenAlex ids

Return early when a row has no primary OpenAlex identifier so the HEI cross-check helper stays type-safe under the stricter pre-commit checks.

* feat(dashboards): add Matomo usage snapshot pipeline

Capture build-time Matomo reporting data in a checked-in snapshot so Quarto can publish historic usage without any client-side credentials.

* feat(dashboards): add site usage dashboard

Publish the most useful Matomo metrics directly on the site so readers can inspect lifetime and month-by-month usage without leaving the NAIF website.

* ci: streamline validation and release builds

Keep deployment and release artifacts aligned with the local validation flow while refreshing the Matomo usage snapshot during automated builds.

* fix(dashboards): stabilise site usage overview presentation

Keep the overview cards readable inside the dashboard tab layout and add the missing listing screenshot and attribution for the site usage page.

* chore(dashboards): refresh Matomo usage snapshot

Populate the site usage dashboard with the latest Matomo export so the published overview reflects the current reporting window totals, traffic sources, and top pages.

* fix(dashboards): harden Matomo usage helpers

* fix(dashboards): update FHNW name for consistency in data representation

* feat(events): add event details for the European Commission workshop on research access and reuse

* fix(events): update registration information for past event to indicate it has taken place

* chore: clean up code structure and remove unused code blocks

---------

Co-authored-by: Moritz Mähr <14755525+maehr@users.noreply.github.com>

Author: maehr

.github/workflows/changelog.yaml

@@ -8,7 +8,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 

.github/workflows/link-check.yml

@@ -16,11 +16,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
 
       - name: Restore lychee cache
         id: restore-cache
-        uses: actions/cache/restore@v4
+        uses: actions/cache/restore@v5
         with:
           path: .lycheecache
           key: cache-lychee-${{ github.ref }}-${{ hashFiles('.lycheerc.toml') }}
@@ -36,33 +36,8 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Set up Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: "3.14"
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v6
-
-      - name: Sync Python environment
-        run: uv sync
-
-      - name: Set up Quarto
-        uses: quarto-dev/quarto-actions/setup@v2
-
-      - name: Render Quarto project
-        run: uv run quarto render
-
-      - name: Rendered HTML link checker
-        uses: lycheeverse/lychee-action@v2
-        with:
-          args: >
-            --offline --config .lycheerc.toml --root-dir ${{ github.workspace }}/_site
-            './_site/**/*.html'
-          fail: true
-
       - name: Save lychee cache
-        uses: actions/cache/save@v4
+        uses: actions/cache/save@v5
         if: always()
         with:
           path: .lycheecache

.github/workflows/quarto-publish.yml

@@ -22,10 +22,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out repository
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
 
       - name: Set up Node.js
-        uses: actions/setup-node@v5
+        uses: actions/setup-node@v6
         with:
           node-version: "24"
           cache: "npm"
@@ -42,10 +42,10 @@ jobs:
     needs: lint
     steps:
       - name: Check out repository
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
 
       - name: Set up Node.js
-        uses: actions/setup-node@v5
+        uses: actions/setup-node@v6
         with:
           node-version: "24"
           cache: "npm"
@@ -59,7 +59,7 @@ jobs:
           python-version: "3.14"
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@v8
 
       - name: Set up R
         uses: r-lib/actions/setup-r@v2
@@ -69,7 +69,7 @@ jobs:
 
       - name: Set up Chrome
         id: setup-chrome
-        uses: browser-actions/setup-chrome@v1
+        uses: browser-actions/setup-chrome@v2
 
       - name: Expose Chrome as google-chrome
         run: sudo ln -s "${{ steps.setup-chrome.outputs.chrome-path }}" /usr/local/bin/google-chrome
@@ -80,20 +80,34 @@ jobs:
       - name: Set up Quarto
         uses: quarto-dev/quarto-actions/setup@v2
 
-      - name: Render Quarto project
-        run: uv run quarto render
+      - name: Install lychee
+        uses: taiki-e/install-action@v2
+        with:
+          tool: lychee
+
+      - name: Fetch Matomo usage snapshot
+        env:
+          MATOMO_TOKEN_AUTH: ${{ secrets.MATOMO_TOKEN_AUTH }}
+          MATOMO_BASE_URL: ${{ vars.MATOMO_BASE_URL }}
+          MATOMO_SITE_ID: ${{ vars.MATOMO_SITE_ID }}
+          MATOMO_PUBLIC_SITE_URL: ${{ vars.MATOMO_PUBLIC_SITE_URL }}
+          MATOMO_REPORT_START_DATE: ${{ vars.MATOMO_REPORT_START_DATE }}
+        run: uv run python scripts/fetch_matomo_usage.py
+
+      - name: Run validation suite
+        run: npm run validate
 
       - name: JamPack optimization
-        run: npx @divriots/jampack ./_site
+        run: npm run jampack
 
       - name: Upload built site artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: built-site
           path: _site
 
       - name: Upload Pages artifact
-        uses: actions/upload-pages-artifact@v4
+        uses: actions/upload-pages-artifact@v5
         with:
           path: _site
 
@@ -108,4 +122,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

.github/workflows/release.yml

@@ -0,0 +1,70 @@
+name: Attach Rendered Site to Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-attach:
+    name: Build site and upload release asset
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8
+
+      - name: Set up R
+        uses: r-lib/actions/setup-r@v2
+
+      - name: Install R dependencies
+        run: Rscript -e 'install.packages("processx")'
+
+      - name: Set up Chrome
+        id: setup-chrome
+        uses: browser-actions/setup-chrome@v2
+
+      - name: Expose Chrome as google-chrome
+        run: sudo ln -s "${{ steps.setup-chrome.outputs.chrome-path }}" /usr/local/bin/google-chrome
+
+      - name: Sync Python environment
+        run: uv sync
+
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
+
+      - name: Fetch Matomo usage snapshot
+        env:
+          MATOMO_TOKEN_AUTH: ${{ secrets.MATOMO_TOKEN_AUTH }}
+          MATOMO_BASE_URL: ${{ vars.MATOMO_BASE_URL }}
+          MATOMO_SITE_ID: ${{ vars.MATOMO_SITE_ID }}
+          MATOMO_PUBLIC_SITE_URL: ${{ vars.MATOMO_PUBLIC_SITE_URL }}
+          MATOMO_REPORT_START_DATE: ${{ vars.MATOMO_REPORT_START_DATE }}
+        run: uv run python scripts/fetch_matomo_usage.py
+
+      - name: Build release archive
+        run:
+          npm run site:build && npm run site:archive -- --tag "${{ github.event.release.tag_name }}"
+
+      - name: Upload release asset
+        uses: softprops/action-gh-release@v3
+        with:
+          files: release-artifacts/site-${{ github.event.release.tag_name }}.zip

.lycheerc.toml

@@ -18,6 +18,8 @@ exclude = [
   "https://epfl.zoom.us/meeting/register/",
   # Python f-string URL templates in dashboard code (contain {identifier} placeholders)
   "https://www.wikidata.org/wiki/",
+  # Wikidata SPARQL intermittently returns 502/504 during automated checks
+  "https://query.wikidata.org/sparql",
   "https://api.crossref.org/funders/",
   "https://www.geonames.org/",
   "https://isni.org/isni/",

.pre-commit-config.yaml

@@ -6,6 +6,25 @@ repos:
         entry: npm run check
         language: system
         stages: [pre-commit]
+      - id: ruff-format
+        name: Ruff format
+        entry: uv run ruff format
+        language: system
+        types: [python]
+        stages: [pre-commit]
+      - id: ruff-check
+        name: Ruff lint
+        entry: uv run ruff check
+        language: system
+        types: [python]
+        stages: [pre-commit]
+      - id: ty-check
+        name: Ty check
+        entry: uv run ty check
+        language: system
+        types: [python]
+        pass_filenames: false
+        stages: [pre-commit]
       - id: lychee-check
         name: Lychee link check
         entry: npm run lychee-check

CONTRIBUTING.md

@@ -14,14 +14,16 @@ Thanks for considering a contribution.
 3. Run:
 
    ```bash
-   npm install
-   uv sync
-   npm run format
-   uv run quarto render
+    npm install
+    uv sync
+    npm run validate
    ```
 
 4. Open a pull request.
 
+For tagged releases, also run `npm run release:prepare -- --tag vX.Y.Z` and commit the generated
+archive before publishing the release so Zenodo captures the rendered site snapshot.
+
 ## Content contributions
 
 - Blog entries must follow the folder-per-entry structure described in `AGENTS.md`.

README.md

@@ -22,6 +22,7 @@ This repository contains the source for the NAIF project website, built with
 - Node.js (for formatting Markdown with Prettier)
 - Python 3.14
 - uv
+- Lychee (for local link checks in `npm run validate`)
 
 ### Install
 
@@ -30,6 +31,8 @@ npm install
 uv sync
 ```
 
+The Git hooks managed by `prek` are installed automatically via npm's `prepare` script.
+
 ### Format and build
 
 ```bash
@@ -57,12 +60,32 @@ Output file:
 
 ### Validate before opening a PR
 
-Run all checks (formatting, linting, type checking, tests, render) in one go:
+Run all checks (formatting, linting, type checking, tests, render, rendered link checks) in one go:
 
 ```bash
 npm run validate
 ```
 
+If `lychee` is not available locally yet:
+
+- macOS: `brew install lychee`
+- Other platforms: see https://lychee.cli.rs/
+
+GitHub Actions runs the same validation suite before building and deploying the site.
+
+### Prepare a release archive for Zenodo
+
+Create a release-ready snapshot of the rendered site and stage it for commit before tagging a
+release:
+
+```bash
+npm run release:prepare -- --tag v1.0.0
+```
+
+This creates `release-artifacts/site-v1.0.0.zip` and stages it for commit. Commit the archive before
+publishing the GitHub release so the tagged repository snapshot contains the rendered site that
+Zenodo will archive.
+
 ### npm scripts reference
 
 #### Quarto
@@ -74,6 +97,7 @@ npm run validate
 | `npm run preview`      | `uv run quarto preview`                | Local dev server with live reload       |
 | `npm run preview:fork` | `uv run quarto preview --profile fork` | Preview locally with fork-specific URLs |
 | `npm run docx`         | `uv run quarto render --profile docx`  | Export site to a single DOCX            |
+| `npm run site:build`   | `render` + `jampack`                   | Build the optimised release site        |
 
 #### Code quality
 
@@ -98,8 +122,10 @@ npm run validate
 | ------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------- |
 | `npm run sync`                  | `uv sync`                                                        | Install/sync Python dependencies                        |
 | `npm run validate`              | check + lint + typecheck + test + render + lychee-check:rendered | Full pre-PR validation                                  |
-| `npm run deploy`                | render + jampack + publish                                       | Build, optimise, and deploy to GitHub Pages             |
+| `npm run deploy`                | site:build + publish                                             | Build, optimise, and deploy to GitHub Pages             |
 | `npm run publish:fork`          | `uv run quarto publish gh-pages --no-render --profile fork`      | Publish a fork build to the fork's GitHub Pages site    |
+| `npm run site:archive`          | `uv run python scripts/release_site_archive.py`                  | Create a versioned ZIP of the rendered site             |
+| `npm run release:prepare`       | site:build + site:archive --stage                                | Build and stage the Zenodo-ready release archive        |
 | `npm run changelog`             | `git-cliff`                                                      | Generate CHANGELOG from commits                         |
 | `npm run commit`                | `cz`                                                             | Commitizen guided commit                                |
 | `npm run lychee-check`          | `lychee`                                                         | Check for broken links in source `.md` and `.qmd` files |