Modernize static site generator stack (Node 22, updated Metalsmith plugins) #2

Merged
AverageMarcus merged 5 commits from update/modernize-metalsmith-stack into master 2026-11-16 14:10:52 +00:00
Collaborator

Changes

Node.js

  • Upgraded from v16 to v22 (latest LTS) via .nvmrc and Dockerfile

Sass

  • Replaced deprecated node-sass with Dart Sass (sass@^1.108.2)
  • Pre-build compilation of SCSS to CSS before Metalsmith run
  • Added .ignore(["css"]) to prevent source SCSS files being copied to build

Metalsmith Plugins

Migrated to modern scoped packages:

  • @metalsmith/markdown (v1.10) replacing metalsmith-markdownit
  • @metalsmith/in-place (v5) replacing metalsmith-in-place v1
  • @metalsmith/layouts (v3) replacing metalsmith-layouts v1
  • @metalsmith/collections (v2) replacing metalsmith-collections v0
  • @metalsmith/markdown + @metalsmith/layouts configured with custom Handlebars jstransformer supporting .html templates
  • metalsmith-pagination for index page pagination
  • gray-matter for YAML front matter extraction

Markdown Rendering

  • Updated to marked v18 with GFM support
  • Custom table renderer adds role="grid" for accessibility
  • Added jstransformer-handlebars for template transforms

Custom Plugins

  • plugins/permalinks.js - Replaces metalsmith-permalinks (which has broken substitute dependency)
  • plugins/handlebars-html.js - Custom jstransformer wrapper that supports .html file extensions for Handlebars templates

Feed

  • Custom RSS feed plugin replaces deprecated metalsmith-feed
  • Generates feed.xml with all 56 posts

Routing

  • filterRoutes.js - Updated regex patterns for Express 4.x compatibility

Templates

  • Removed deprecated markdown="1" from picture.html and tweet.html

Docker

  • Base image: node:22-alpine
  • Build dependencies: python3, make, gcc, g++
  • Engine: 22

Build Verification

  • 69 HTML files generated successfully
  • 56 posts
  • 12 pagination pages
  • RSS feed (feed.xml) generated
  • Sitemap (sitemap.xml) generated
  • SCSS compilation working (style.css)

All build output is in the build/ directory.

## Changes ### Node.js - Upgraded from v16 to v22 (latest LTS) via `.nvmrc` and `Dockerfile` ### Sass - Replaced deprecated `node-sass` with Dart Sass (`sass@^1.108.2`) - Pre-build compilation of SCSS to CSS before Metalsmith run - Added `.ignore(["css"])` to prevent source SCSS files being copied to build ### Metalsmith Plugins Migrated to modern scoped packages: - `@metalsmith/markdown` (v1.10) replacing `metalsmith-markdownit` - `@metalsmith/in-place` (v5) replacing `metalsmith-in-place` v1 - `@metalsmith/layouts` (v3) replacing `metalsmith-layouts` v1 - `@metalsmith/collections` (v2) replacing `metalsmith-collections` v0 - `@metalsmith/markdown` + `@metalsmith/layouts` configured with custom Handlebars jstransformer supporting `.html` templates - `metalsmith-pagination` for index page pagination - `gray-matter` for YAML front matter extraction ### Markdown Rendering - Updated to `marked` v18 with GFM support - Custom table renderer adds `role="grid"` for accessibility - Added `jstransformer-handlebars` for template transforms ### Custom Plugins - `plugins/permalinks.js` - Replaces `metalsmith-permalinks` (which has broken `substitute` dependency) - `plugins/handlebars-html.js` - Custom jstransformer wrapper that supports `.html` file extensions for Handlebars templates ### Feed - Custom RSS feed plugin replaces deprecated `metalsmith-feed` - Generates `feed.xml` with all 56 posts ### Routing - `filterRoutes.js` - Updated regex patterns for Express 4.x compatibility ### Templates - Removed deprecated `markdown="1"` from `picture.html` and `tweet.html` ### Docker - Base image: `node:22-alpine` - Build dependencies: python3, make, gcc, g++ - Engine: 22 ## Build Verification - 69 HTML files generated successfully - 56 posts - 12 pagination pages - RSS feed (feed.xml) generated - Sitemap (sitemap.xml) generated - SCSS compilation working (style.css) All build output is in the `build/` directory.
hermes-agent added 1 commit 2026-11-16 10:39:51 +00:00
- Node.js: Upgraded from v16 to v22 (latest LTS)
- SASS: Replaced deprecated node-sass with Dart Sass (sass package)
- Metalsmith plugins: Migrated to modern scoped packages:
  - @metalsmith/markdown (v1.10) replacing metalsmith-markdownit
  - @metalsmith/in-place (v5) replacing metalsmith-in-place v1
  - @metalsmith/layouts (v3) replacing metalsmith-layouts v1
  - @metalsmith/collections (v2) replacing metalsmith-collections v0
  - Added metalsmith-define for site metadata
  - Added gray-matter for YAML front matter extraction
- Markdown rendering: Updated to marked v18 for GFM support
- Express: Kept at v4.x (stable, compatible)
- Handlebars: Updated to v4.7 (latest)
- Custom plugins: Created local permalinks and handlebars-html plugins
  - Custom permalinks plugin replaces metalsmith-permalinks (broken substitute dep)
  - Custom handlebars jstransformer wrapper supports .html extension
- Feed generation: Custom RSS plugin (replaces deprecated metalsmith-feed)
- filterRoutes: Updated regex patterns for Express compatibility
- Template changes: Removed deprecated markdown="1" from partials
- Docker: Updated Dockerfile to use Node 22 Alpine
- Collection patterns: Updated to support both .md and .markdown extensions
- Pipeline: Reordered for correct metadata flow (front matter → markdown → layouts → permalinks)
hermes-agent force-pushed update/modernize-metalsmith-stack from 0f021e9672 to 7a5c031b1d 2026-11-16 10:39:51 +00:00 Compare
hermes-agent changed title from Modernize static site generator stack to Modernize static site generator stack (Node 22, updated Metalsmith plugins) 2026-11-16 10:40:29 +00:00
hermes-agent added 1 commit 2026-11-16 11:04:36 +00:00
The .ignore(['css']) pattern was preventing all CSS files in src/css/
from being copied to the build directory. Only SCSS source files should
be ignored - pre-compiled CSS dependencies like pico.min.css and
zenburn.css need to be served by the static file server.
hermes-agent added 1 commit 2026-11-16 11:10:35 +00:00
The v2 API uses sort: 'date:desc' instead of sortBy: 'date' + reverse:
true. This ensures posts display newest-first on the index page.
hermes-agent added 1 commit 2026-11-16 12:15:07 +00:00
- Use front-matter title for post slug (not filename)
- Remove /posts/ prefix from URLs to match production
- Remove /pages/ prefix from page URLs to match production
- Fix OG URL on index page (no longer shows .html extension)
- Remove dots from slugs (fixes T.I.L. posts being files not dirs)
- Collapse consecutive dashes in slugs
- Remove / from slug character class (prevents URL paths in slugs)
- Skip index.html in permalink plugin (already has correct path from pagination)

Production URL format: /YYYY-MM-DD-full-title-slug/
hermes-agent added 1 commit 2026-11-16 13:35:18 +00:00
- Add <guid> elements to RSS feed (matching <link> URLs)
- Preserve dots in slugs (t.i.l. instead of til) to match production
- URLs now match production format: /YYYY-MM-DD-title-slug/
  No /posts/ prefix, with dots preserved for T.I.L. posts
- This ensures feed readers won't mark posts as new
AverageMarcus merged commit c69e2cbb97 into master 2026-11-16 14:10:52 +00:00
Sign in to join this conversation.
No Reviewers
No labels
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: AverageMarcus/blog#2