Tech Stack

• Astro 5 (AstroPaper theme)
• TypeScript
• Tailwind CSS 4
• Pagefind (static search)
• Shiki (syntax highlighting)
• Satori + resvg-js (OG image generation)
• remark-toc + remark-collapse
• pnpm

Architecture

• Static site built with astro build and deployed statically.
• Journal entries live at src/data/blog/_YYYY-MM-DD/journal.md, one per development session, with associated images in src/assets/images/YYYY-MM-DD/.
• Astro’s content collections API validates frontmatter schema across all entries (title, description, tags, pubDatetime).
• Each entry follows a fixed template: a TLDR, the main work completed, challenges, learnings, and screenshots.
• Pagefind builds a client-side search index by scanning the dist/ output after astro build, then copies the index to public/ before serving.
• OG images are generated at build time from post metadata using Satori and resvg-js.
• A custom Shiki transformer adds filename banners to code blocks, alongside the standard transformers for diff notation and line highlighting.
• A remark plugin auto-generates a table of contents from headings in each entry, collapsed by default.

Challenges

• Pagefind requires a completed dist/ directory before it can index anything, so the build script chains astro build → pagefind --site dist → copy index to public/. The dev server cannot serve search results without a prior full build.
• Maintaining consistent journal entries alongside active development requires discipline.
  • The fixed entry template lowers the friction enough to make it practical.

Learnings

• Pagefind integrates cleanly into an Astro site with no server-side infrastructure needed, and the default search UI requires no customization.
• AstroPaper covers most of what a dev journal needs out of the box: dark mode, RSS feed, tag filtering, OG image generation, and pagination.
• A fixed post template keeps entries consistent and makes the journal scannable without requiring any enforcement mechanism.
• Writing entries close to each development session is significantly easier than reconstructing decisions days later.

For the Future

• Add a stats or summary page showing total entry count, most-used tags, and development activity over time.
• Cross-reference related journal entries by linking between sessions that cover the same feature or subsystem.
• Automate parts of the entry creation process, such as pre-populating the date and linking to relevant commits.
• Explore RAG systems that could answer questions about previous design choices or jog my memory.