HangerThem/blog.hangerthem.com
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Bug fixes, SEO, performance and accessibility pass #1

Merged
HangerThem merged 6 commits from dev into main 2026-10-19 12:41:44 +00:00
Conversation 0 Commits 6 Files changed 48 +817 -1120
HangerThem commented 2026-10-19 12:40:19 +00:00
Owner
Copy link

Summary

A cleanup pass across the blog: route and feed bugs fixed, SEO basics added, smaller and lazier images, accessibility fixes, and a real README. No content or design changes beyond small fixes.

Bug fixes

  • Tag/category pages: static params now use slugs, so pre-rendered pages match the links (before, /tags/standard-model was only rendered on demand and the pre-built pages said "Tag not found"). Unknown slugs now return a real 404, and there's a new not-found page.
  • Recently updated: sorts by last modification before taking the top 5, so older posts that were updated recently now show up.
  • Atom feed: rel="self" now points to /feed.xml (was /feed); <updated> uses the updated frontmatter field.
  • No-JS flash: the no-js → js class swap runs in an inline <head> script before first paint, not after hydration.
  • Markdown links: only internal paths go through next/link; #anchors, mailto: and links without an href no longer break.
  • Invalid HTML: images in a paragraph together with text (e.g. "Screenshots:" followed by images on the Projects page) produced <p><figure> and a hydration error. Those paragraphs are now split.
  • Dates: frontmatter dates are normalized to ISO, so <time datetime> values are valid. Formatting is pinned to Europe/Prague so a UTC build server can't shift a date by a day.

SEO

  • sitemap.xml and robots.txt
  • Canonical URLs, Twitter cards and a feed link on every page, built by a shared pageMetadata() helper
  • Generated Open Graph images: a site card, and for each post its cover image or a branded title card (pre-rendered at build time)
  • BlogPosting JSON-LD on post pages

Performance

  • Only the post cover and the latest-post image are preloaded (was: every image)
  • In-post image quality 100 → 90, plus responsive sizes
  • Screenshots downscaled to 1800px wide; linkboard-old.png converted to WebP (3.1 MB → 60 KB)
  • CodeWrapper is now a server component; only the copy button ships to the client
  • Mermaid CDN script pinned to 11.17.2 for reproducible builds

Accessibility

  • Accessible names for icon-only links (share, social, mobile nav) and aria-current on active nav items
  • Copy button: uses React state instead of mutating innerHTML, handles clipboard errors, announces the result to screen readers, and is no longer inside an aria-hidden header
  • Code-block line numbers hidden from screen readers
  • Image captions: the Markdown "title" becomes the caption; captions that only repeat the alt text are hidden from screen readers

Content & maintenance

  • Frontmatter validation: a missing or malformed field fails the build and names the file, instead of rendering a broken post
  • draft: true support: drafts only render in development
  • About/Projects/Setup pages share one MarkdownPage component; tag/category lists share PostList
  • Markdown rendering is cached, so metadata and page share one render
  • New README covering features, env vars, frontmatter schema, Markdown extensions and deployment
  • Removed unused ESLint setup and the unrelated hast package; oxlint, oxfmt and puppeteer moved to devDependencies (locked versions unchanged)
  • Typo fix in the Tessera cover alt text; removed unused math/mermaid flags from two posts

Deployment notes

  • SITE_URL is now required: the build fails with a clear error if it's missing.
  • Puppeteer is a devDependency now: Nixpacks installs dev dependencies for the build by default, but check that Mermaid diagrams render on the first deploy (the Standard Model post has one).

Testing

  • tsc --noEmit and bun run lint pass
  • bun run build passes; all 81 pages are generated statically
  • Smoke-tested next start: posts, tags, categories, feed, sitemap and OG images return 200; unknown tags and routes return 404
  • No block elements nested inside <p> in any built page
## Summary A cleanup pass across the blog: route and feed bugs fixed, SEO basics added, smaller and lazier images, accessibility fixes, and a real README. No content or design changes beyond small fixes. ## Bug fixes - **Tag/category pages**: static params now use slugs, so pre-rendered pages match the links (before, `/tags/standard-model` was only rendered on demand and the pre-built pages said "Tag not found"). Unknown slugs now return a real 404, and there's a new not-found page. - **Recently updated**: sorts by last modification *before* taking the top 5, so older posts that were updated recently now show up. - **Atom feed**: `rel="self"` now points to `/feed.xml` (was `/feed`); `<updated>` uses the `updated` frontmatter field. - **No-JS flash**: the `no-js` → `js` class swap runs in an inline `<head>` script before first paint, not after hydration. - **Markdown links**: only internal paths go through `next/link`; `#anchors`, `mailto:` and links without an `href` no longer break. - **Invalid HTML**: images in a paragraph together with text (e.g. "**Screenshots:**" followed by images on the Projects page) produced `<p><figure>` and a hydration error. Those paragraphs are now split. - **Dates**: frontmatter dates are normalized to ISO, so `<time datetime>` values are valid. Formatting is pinned to Europe/Prague so a UTC build server can't shift a date by a day. ## SEO - `sitemap.xml` and `robots.txt` - Canonical URLs, Twitter cards and a feed link on every page, built by a shared `pageMetadata()` helper - Generated Open Graph images: a site card, and for each post its cover image or a branded title card (pre-rendered at build time) - `BlogPosting` JSON-LD on post pages ## Performance - Only the post cover and the latest-post image are preloaded (was: every image) - In-post image quality 100 → 90, plus responsive `sizes` - Screenshots downscaled to 1800px wide; `linkboard-old.png` converted to WebP (3.1 MB → 60 KB) - `CodeWrapper` is now a server component; only the copy button ships to the client - Mermaid CDN script pinned to `11.17.2` for reproducible builds ## Accessibility - Accessible names for icon-only links (share, social, mobile nav) and `aria-current` on active nav items - Copy button: uses React state instead of mutating `innerHTML`, handles clipboard errors, announces the result to screen readers, and is no longer inside an `aria-hidden` header - Code-block line numbers hidden from screen readers - Image captions: the Markdown `"title"` becomes the caption; captions that only repeat the alt text are hidden from screen readers ## Content & maintenance - **Frontmatter validation**: a missing or malformed field fails the build and names the file, instead of rendering a broken post - **`draft: true` support**: drafts only render in development - About/Projects/Setup pages share one `MarkdownPage` component; tag/category lists share `PostList` - Markdown rendering is cached, so metadata and page share one render - New README covering features, env vars, frontmatter schema, Markdown extensions and deployment - Removed unused ESLint setup and the unrelated `hast` package; `oxlint`, `oxfmt` and `puppeteer` moved to devDependencies (locked versions unchanged) - Typo fix in the Tessera cover alt text; removed unused `math`/`mermaid` flags from two posts ## Deployment notes - **`SITE_URL` is now required**: the build fails with a clear error if it's missing. - **Puppeteer is a devDependency now**: Nixpacks installs dev dependencies for the build by default, but check that Mermaid diagrams render on the first deploy (the Standard Model post has one). ## Testing - `tsc --noEmit` and `bun run lint` pass - `bun run build` passes; all 81 pages are generated statically - Smoke-tested `next start`: posts, tags, categories, feed, sitemap and OG images return 200; unknown tags and routes return 404 - No block elements nested inside `<p>` in any built page
HangerThem added 6 commits 2026-10-19 12:40:20 +00:00 
- Slugify tag/category static params so pre-rendered pages match links;
  disable dynamic params and return a real 404 via notFound()
- Drop bogus generateStaticParams from the tags/categories index pages
- Add a styled not-found page
- Sort 'Recently updated' by last modification before slicing
- Atom feed: correct rel=self URL, use updated dates, valid content type
- Swap no-js -> js class in an inline head script before first paint
- Markdown links: only route internal paths through next/link and
  tolerate missing hrefs
- Only preload the post cover and latest-post image instead of every image
- Drop in-post image quality from 100 to 90 and add responsive sizes
- Downscale 2940px screenshots to 1800px; convert linkboard-old to WebP
  (3.1 MB -> 60 KB)
- Make CodeWrapper a server component; only CopyButton ships to the client
- Pin the Mermaid CDN script to an exact version for reproducible builds
- Add sitemap.ts and robots.ts
- pageMetadata() helper: consistent title, canonical URL, Open Graph,
  Twitter card and feed alternate on every page
- Generated OG images: a site card, and per post either the cover image
  or a branded title card (pre-rendered at build)
- BlogPosting JSON-LD on post pages
- Fail fast with a clear error when SITE_URL is missing

Content loading:
- Validate post frontmatter at build time and normalize dates to ISO
  (fixes invalid <time datetime> values)
- Add draft: true support (drafts only render in development)
- Cache markdown rendering so metadata and page share one render
- Replace the three copy-pasted about/projects/setup pages with a shared
  MarkdownPage component
- aria-labels on share links, sidebar social links and mobile nav icons
- aria-current on active nav links
- CopyButton: React state instead of innerHTML mutation, clipboard error
  handling, accessible label and a polite live region for feedback

(Related code-block and image-caption a11y fixes landed with the
ImageWrapper/CodeWrapper rewrite in the previous perf commit.)
- Replace the create-next-app README with real project docs (features,
  env vars, frontmatter schema, Markdown extensions, deployment)
- Drop ESLint (unused by any script; oxlint is the linter) and the
  unrelated 'hast' package; move oxlint, oxfmt and puppeteer to
  devDependencies (locked versions unchanged)
- Extract PostList, used by the tag and category pages
- Use shared Intl formatters for post dates, pinned to Europe/Prague so
  the build server's timezone can't shift dates
- Use <h1> for the tag/category page headings (same styling)
- Remove math/mermaid flags from posts that don't use them; fix a typo
  in the Tessera cover alt text
Images render as <figure>, which isn't allowed inside <p>. The unwrap
plugin only handled paragraphs containing a single image, so a label
followed by images on the next lines (as on the Projects page) produced
invalid HTML and a hydration error. Split such paragraphs instead.
HangerThem self-assigned this 2026-10-19 12:41:19 +00:00
HangerThem merged commit 30ef0d611e into main 2026-10-19 12:41:44 +00:00
HangerThem deleted branch dev 2026-10-19 12:41:45 +00:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
HangerThem
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: HangerThem/blog.hangerthem.com#1
No description provided.
Delete branch "dev"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?