workman.tech

Source for Ryan Workman's personal blog at workman.tech. Posts are authored in markdown, rendered to static HTML by a small Node build script, and served by GitHub Pages from the repo root.

Tech stack

• Node.js build script (markdown-it + gray-matter), with prettier formatting the generated HTML and html-validate linting it
• Vanilla HTML and CSS
• GitHub Pages for hosting
• No frameworks or bundler. A GitHub Actions workflow validates each pull request (build freshness + HTML lint)

Local setup

1. Install Node.js 22.17 or newer (required by the html-validate lint tooling; CI runs Node 24).
2. npm install.
3. To preview the site, run npm run dev and visit http://localhost:3000. This is a thin wrapper around python3 -m http.server 3000 — it serves the repo root over HTTP so absolute paths like /css/style.css and /images/... resolve correctly. Requires Python 3 on your PATH.

Adding a post

1. Create _posts/<theme>/YYYY-MM-DD-slug.md. The parent folder name is the theme and becomes part of the URL.

2. Add frontmatter at the top of the file:

   ---
   title: rails perf wins from a 3-month audit
   date: 2026-06-01
   description: short blurb used for the meta description and OG tags
   tags: [ruby, rails, performance]
   ---

   title and date are required. description and tags are optional.

3. Run npm run build.

4. Review the diff — both the source .md and the generated HTML.

5. Commit everything: the markdown source and the generated HTML inside <theme>/.

6. Push. GitHub Pages will redeploy automatically.

The published URL pattern is https://workman.tech/<theme>/YYYY-MM-DD-slug.html.

Note: The build runs locally; CI does not build the site for you. Instead, a GitHub Actions workflow re-runs the build on every pull request and fails if the committed HTML doesn't match a fresh build (it also lints the HTML). So if you commit a post's source .md without running npm run build, CI will catch it. Always run npm run build and commit the generated HTML alongside the source.

Commands

• npm run dev — start a local static server on port 3000 for previewing the site.
• npm run build — render all posts and regenerate the homepage post list. Every generated file is formatted with Prettier.
• npm run lint:html — validate index.html and the generated theme HTML with html-validate.
• npm run lint:fix — auto-format source files with Prettier. (html-validate has no autofix, so HTML problems must be fixed by hand.)
• npm run clean — remove generated theme directories and reset the homepage post-list region to its empty state. Only touches files that start with the <!-- generated by build.js --> marker, so hand-edited content is safe.

Deployment

GitHub Pages serves the repo root. Any push to main triggers a redeploy and is usually live within a minute. The custom domain is configured via the CNAME file.

More

See CLAUDE.md for the architecture details and the list of deferred follow-ups (RSS, sitemap, per-tag pages, syntax highlighting, OG images).