feat(new site): a full redo of the current website using the (modified) clean hugo theme

.github/workflows/build-site.yml

@@ -1,4 +1,4 @@
-name: Build and Jekyll site and run htmlproofer
+name: Build Hugo site and run htmlproofer
 
 on:
   pull_request:
@@ -17,20 +17,25 @@ jobs:
       - name: Check out the code
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
-      - name: Fetch main
-        run: |
-          git fetch origin main --depth 1
-          git branch
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: "20"
+          cache: npm
+
+      - name: Install npm dependencies
+        run: npm ci
 
-      - name: Setup Ruby
-        uses: ruby/setup-ruby@6aaa311d81eba98ae12eaffbcb63296ace0efcde # v1.307.0
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@2752ce1d29631191ea3f27c23495fa06139a5b78 # v3
         with:
-          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+          hugo-version: "0.139.4"
+          extended: true
 
-      - name: Build with Jekyll
-        run: bundle exec jekyll build
+      - name: Build with Hugo
+        run: hugo --gc --minify
         env:
-          JEKYLL_ENV: production
+          HUGO_ENV: production
 
       - name: Restore lychee cache
         uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
@@ -43,18 +48,17 @@ jobs:
 
       - name: Check links with lychee
         id: lychee
-        uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 #v2.8.0
+        uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2.8.0
         with:
           fail: true
-          args: --root-dir _site _site
+          args: --root-dir public public
         env:
-          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Check HTML using htmlproofer
-        uses: chabad360/htmlproofer@c2750eb7eb937599ac859517e7dd23a29f1b3ed7 #v2
+        uses: chabad360/htmlproofer@c2750eb7eb937599ac859517e7dd23a29f1b3ed7 # v2
         with:
-          directory: "_site"
+          directory: "public"
           arguments: |
-            --ignore-files "/.+\/_posts\/README.md"
             --ignore-urls "/^https?:\/\/(www\.)?pyopensci\.org\//"
             --checks "Images,Scripts"

.gitignore

@@ -17,3 +17,8 @@ node_modules/*
 public/
 resources/
 .lycheecache
+
+# site redesign
+.cursor/*
+_law_tests/*
+jekyll/*

.pre-commit-config.yaml

@@ -35,6 +35,7 @@ repos:
     hooks:
       - id: codespell
         exclude_types:
+          - css
           - javascript
           - scss
           - yaml

DEVELOPMENT.md

@@ -0,0 +1,186 @@
+# Hugo site development notes
+
+Temporary reference for the pyOpenSci Hugo migration. Focus: how CSS is
+organized and built. See also `README.md` for install and serve commands.
+
+## Quick start
+
+From the repository root:
+
+```bash
+npm ci
+hugo server --disableFastRender
+```
+
+Hugo Extended is required (SCSS + PostCSS). The first run needs `npm ci` so
+PostCSS can run during the asset pipeline.
+
+Do **not** commit build output: `public/`, `resources/`, and `.hugo_build.lock`
+are gitignored.
+
+## Two CSS locations (do not confuse them)
+
+Hugo treats `assets/` and `static/` differently.
+
+| Location | Role | Committed? | Built on deploy? |
+|----------|------|------------|------------------|
+| `themes/clean-hugo/assets/css/` | Main site SCSS source | Yes (source) | Yes → compiled CSS |
+| `themes/clean-hugo/static/css/syntax.css` | Code-block highlighting only | Yes (as-is) | No — copied to site |
+
+There is no `static/scss/` folder. All authored styles live under
+`assets/css/` as SCSS partials.
+
+### `assets/css/` — main styling (SCSS)
+
+* Entry file: `themes/clean-hugo/assets/css/site.scss` (see **Jekyll coexistence**
+  below — normally this would be `main.scss`)
+* Partials: `_footer.scss`, `_blog.scss`, `_events.scss`, etc.
+* Hugo compiles this at **build time** (local `hugo server` or Netlify).
+* Output goes to `public/css/site.min.<hash>.css` — never commit that file.
+
+### `static/css/syntax.css` — code highlighting only
+
+* One pre-generated file for Chroma/monokai highlighting in fenced code blocks.
+* Served as `/css/syntax.css` with no processing.
+* Originally generated with:
+  `hugo gen chromastyles --style=monokai`
+* Not related to layout, footer, blog cards, or brand colors.
+
+## Build pipeline (what happens on `hugo server` / Netlify)
+
+Defined in `themes/clean-hugo/layouts/_default/baseof.html`:
+
+1. **Inline brand colors** — CSS custom properties from `hugo.toml`
+   `[params.theme.colors]` (injected in a `<style>` block in `<head>`).
+2. **Main stylesheet** — Hugo Pipes pipeline:
+
+   ```go
+   {{ $styles := resources.Get "css/site.scss" | toCSS | postCSS | minify | fingerprint }}
+   ```
+
+   Steps: SCSS → CSS → PostCSS (autoprefixer) → minify → fingerprinted URL.
+
+3. **Syntax CSS** — plain link to `/css/syntax.css` from theme `static/`.
+
+Root `package.json` and `postcss.config.js` exist **for step 2 only**. They are
+not used by Jekyll.
+
+## SCSS file map
+
+`site.scss` imports partials in this order (simplified):
+
+| Partial | Purpose |
+|---------|---------|
+| `_variables.scss` | Breakpoints, spacing, shadows, typography tokens |
+| `_mixins.scss` | Shared SCSS mixins |
+| `_buttons.scss` | Button tiers |
+| `_utilities.scss` | Skip links, a11y helpers |
+| *(base rules in site.scss)* | Box-sizing, body, headings |
+| `_navigation.scss` | Header, nav, mobile menu |
+| `_content.scss` | Prose / page content |
+| `_blog.scss` | Single post layout |
+| `_blog-listing.scss` | Blog index, cards, filters |
+| `_events.scss` | Events listing and detail |
+| `_footer.scss` | Site footer |
+| `_hero.scss` | Hero sections |
+| `_cards.scss` | Card grids |
+| `_shortcodes.scss` | Shortcode markup (admonitions, cards, etc.) |
+| `_admonition.scss` | Callout blocks |
+| `_code.scss` | Inline code styling (not syntax colors) |
+| `_figure.scss` | Figures and captions |
+| Other partials | Gallery, packages, people, docs, swoosh, filters, … |
+
+When adding styles, prefer the partial that matches the component. Extend
+existing partials before adding new files.
+
+## Colors and typography
+
+**Brand colors** — set in `hugo.toml` under `[params.theme.colors]`. These
+become CSS variables (e.g. `--color-primary`) at build time. Prefer changing
+colors there for site-wide brand updates.
+
+**SCSS variables** — in `_variables.scss` (`$spacing-md`, `$breakpoint-lg`,
+etc.). Use for layout, spacing, and component structure inside the theme.
+
+**Fonts** — loaded via `@font-face` in `site.scss` from
+`themes/clean-hugo/static/fonts/`. Font family names are configured in
+`hugo.toml` `[params.theme.fonts]`.
+
+## Site `static/` vs theme `static/`
+
+Two different `static/` trees:
+
+| Path | Contents |
+|------|----------|
+| `static/` (repo root) | Site images (`static/images/`), favicons, `CNAME` → published as `/images/...`, `/favicon.ico`, etc. |
+| `themes/clean-hugo/static/` | Theme assets: fonts, JS, `css/syntax.css` → bundled with theme |
+
+Do not move site images into the theme unless they are truly theme-only.
+
+## Local workflow for CSS changes
+
+1. Edit SCSS under `themes/clean-hugo/assets/css/`.
+2. Save — `hugo server --disableFastRender` rebuilds automatically.
+3. If PostCSS errors mention `npx` or `postcss-cli`, run `npm ci` at repo root.
+4. Commit **SCSS changes only** — not `public/` or `resources/`.
+
+To regenerate syntax highlighting after changing `hugo.toml`
+`[markup.highlight]` style:
+
+```bash
+hugo gen chromastyles --style=monokai > themes/clean-hugo/static/css/syntax.css
+```
+
+Then commit the updated `syntax.css`.
+
+## Jekyll coexistence (temporary — revert at cutover)
+
+While Jekyll and Hugo share this repo, **root** `assets/css/main.scss` remains
+on `main`. That file is Jekyll’s Minimal Mistakes entry point and starts with
+YAML front matter (`---`), which Hugo’s SCSS compiler cannot parse.
+
+Hugo’s `resources.Get "css/main.scss"` resolves **site `assets/` before theme
+`assets/`**, so the Jekyll file shadows the theme stylesheet and Netlify builds
+fail.
+
+**Workaround (current):**
+
+* Theme entry SCSS is named `site.scss` (not `main.scss`).
+* Layouts load `resources.Get "css/site.scss"` in `baseof.html` and `404.html`.
+
+**Revert when Jekyll is retired** (after root Jekyll assets are removed or
+moved under `jekyll/`):
+
+1. Rename `themes/clean-hugo/assets/css/site.scss` → `main.scss`.
+2. Update `baseof.html` and `404.html` to `resources.Get "css/main.scss"`.
+3. Remove this section from `DEVELOPMENT.md`.
+
+## Netlify
+
+`netlify.toml` runs `npm ci && hugo --gc --minify`. CSS is built on Netlify the
+same way as locally. No separate CSS build step or committed compiled bundle is
+required for the main stylesheet.
+
+## GitHub Actions (CI)
+
+On pull requests and pushes to `main`, `.github/workflows/build-site.yml` runs
+the same Hugo build as Netlify, then validates the output:
+
+1. **Setup** — `npm ci` (PostCSS deps), Hugo Extended **0.139.4** (matches
+   `netlify.toml` `HUGO_VERSION`).
+2. **Build** — `hugo --gc --minify` with `HUGO_ENV=production` → output in
+   `public/`.
+3. **Link check** — [lychee](https://github.com/lycheeverse/lychee) against
+   `public/` (config in `lychee.toml`, domain skips in `.lycheeignore`).
+4. **HTML check** — [htmlproofer](https://github.com/gjtorikian/html-proofer) on
+   `public/` (images and scripts; skips live pyopensci.org URLs that lag deploy).
+
+CircleCI and the CircleCI artifact redirector were removed during the Hugo
+migration.
+
+**Still on Jekyll (migrate later):**
+
+| Workflow | Purpose |
+|----------|---------|
+| `.github/workflows/linkcheck.yml` | Weekly scheduled link check |
+| `.github/workflows/deploy-gh-pages.yml` | GitHub Pages deploy badge in README |

_data/packages.yml

@@ -1724,7 +1724,7 @@
       github_username: '2023-12-13'
   archive:
   version_accepted: TBD
-  date_accepted: missing
+  date_accepted: '2026-03-11'
   created_at: 2023-11-17 20:39:40+00:00
   updated_at: 2026-05-07 15:36:30+00:00
   closed_at: