Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
24 changes: 0 additions & 24 deletions .circleci/config.yml

This file was deleted.

38 changes: 21 additions & 17 deletions .github/workflows/build-site.yml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
name: Build and Jekyll site and run htmlproofer
name: Build Hugo site and run htmlproofer

on:
pull_request:
Expand All @@ -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
Expand All @@ -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"
27 changes: 0 additions & 27 deletions .github/workflows/circleci-artifact-redirector.yml

This file was deleted.

5 changes: 5 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -17,3 +17,8 @@ node_modules/*
public/
resources/
.lycheecache

# site redesign
.cursor/*
_law_tests/*
jekyll/*
1 change: 1 addition & 0 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ repos:
hooks:
- id: codespell
exclude_types:
- css
- javascript
- scss
- yaml
Expand Down
186 changes: 186 additions & 0 deletions DEVELOPMENT.md
Original file line number Diff line number Diff line change
@@ -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 |
2 changes: 1 addition & 1 deletion _data/packages.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
Loading
Loading