For the last twenty years, a large part of software development has been guided by a very simple reflex: when the platform feels too low-level, we install an abstraction.
\nAt first, this was not only reasonable, it was necessary. Platforms were incomplete, browser behavior was inconsistent, standard libraries were often limited, and teams needed shared mental models to ship products at a human pace. Frameworks and libraries gave us vocabulary, structure, conventions, and a way to avoid solving the same problems over and over again.
\nThe problem is that, over time, this useful reflex became almost automatic. Need UI composition? Install a framework. Need routing, state management, validation, forms, styling, animation, authentication glue, build orchestration, dependency injection, data fetching, queues, command handling, or configuration management? Install something.
\nEventually, the product starts becoming only one part of the system. The other part is a carefully negotiated dependency graph, where every new feature has to pass through somebody else's assumptions, release cycle, architecture, migration path, documentation quality, security posture, and long-term maintenance choices.
\nThis is not a frontend problem. It is not a JavaScript problem. It is not a React problem. It is not even a framework problem. It is a software problem.
\nEvery ecosystem has its own version of this story. JavaScript has frontend frameworks and npm. Python has web frameworks, ML stacks, data tools, and long chains of packages. Java has decades of enterprise abstractions. .NET has its own layered ecosystems. PHP, Ruby, Go, Rust, Swift, Kotlin, and C# all have communities that build towers of convenience on top of native language and runtime features.
\nAgain, this did not happen because developers were careless. It happened because abstractions are one of the main tools we have for dealing with complexity. Software is abstraction. The real question is not whether we should use abstractions, but where they should live, who should own them, how much of them should run in production, and whether borrowing them is still the best economic choice.
\nThat question is becoming more urgent because the ground is moving. The next major abstraction layer may not be another framework. The next major abstraction layer may be the model.
\nFrameworks exist because humans need constraints. We need names, conventions, file structures, lifecycle models, shared patterns, and a limited number of concepts to keep in our heads at the same time. A framework is not just code. It is a cognitive compression format.
\nIt tells us how to think about the system. Do not think about everything at once. Think in components, routes, controllers, models, hooks, stores, services, middleware, providers, modules, or pipelines. This is extremely useful when human developers are the only abstraction engine in the loop, because humans need stable shapes to coordinate work, communicate intent, and reduce ambiguity.
\nBut LLMs do not need abstractions in exactly the same way.
\nA model does not care whether a pattern is called a hook, a provider, a composable, a bean, a service, a trait, a reducer, a module, or a pipeline. Those names still matter to us, because they help teams communicate and maintain the system, but they are not the deepest source of quality for AI-assisted software.
\nWhat a model needs is context. It needs constraints. It needs examples, tests, schemas, documentation, review rules, runtime signals, tool access, and clear success criteria. In other words, the most important abstraction for an AI-assisted codebase is not always the framework used by the application. It is the operational environment around the codebase.
\nThat moves the center of gravity.
\nInstead of placing all best practices inside runtime abstractions, we can start placing more of them inside instructions, tests, static analysis, design tokens, architecture rules, accessibility checks, security policies, and project-specific agent skills. The abstraction is still there, but it is no longer necessarily something we ship to users or execute on every request.
\nThis is a very different kind of software architecture.
\nThe next abstraction layer will increasingly be made of things that surround the code rather than things that always run inside it. MCP servers, agent skills, local LLMs, cloud LLMs, project-specific prompts, typed schemas, linters, formatters, test suites, static analysis, design tokens, accessibility rules, security policies, architecture decision records, code review agents, and documentation indexed as working memory all point in the same direction.
\nThey create an environment where code can be generated, constrained, checked, refactored, and reviewed with more project awareness than before.
\nThis does not mean we stop using abstractions. That would make no sense. It means we can stop shipping so many borrowed abstractions to production when their main value is no longer runtime behavior, but repetition, convention, scaffolding, and guidance.
\nA model can generate repetitive implementation. A linter can enforce a project rule. A type system can constrain a data shape. A test can verify behavior. An agent can apply the same refactor across many files. A design system can become tokens, fixtures, examples, and visual checks. A security rule can become a gate. An accessibility expectation can become part of the definition of done.
\nAt that point, many dependencies start to look different. Some still provide deep value and should absolutely be used. Others begin to look less like leverage and more like inherited risk.
\nThe question changes from \"which library should we install?\" to \"should this be a dependency at all?\"
\nDependencies are not free. They increase bundle size, install time, build complexity, runtime surface, security exposure, version drift, documentation debt, maintenance overhead, and future migration cost.
\nThose are the obvious costs. The deeper cost is architectural.
\nEvery dependency imports somebody else's decisions into your product. It brings assumptions about how problems should be modeled, how APIs should behave, how edge cases should be handled, and how the future should evolve. It becomes part of your onboarding path, hiring profile, debugging surface, security model, review process, and long-term roadmap.
\nThe software industry loves reuse, and for good reason. Reuse can be powerful. But reuse is also coupling, and coupling has to be paid for.
\nThe npm ecosystem makes this easy to see because it is large, fast-moving, and deeply interconnected, but the same dynamic exists in every ecosystem. Sonatype reported more than 454,600 new malicious packages identified throughout 2025 across major open-source ecosystems, bringing the cumulative total of known and blocked malware above 1.233 million packages. Research on npm supply-chain weak links also shows how package metadata, install scripts, expired maintainer domains, inactive maintainers, and account takeover opportunities can expose thousands of downstream packages.
\nThis does not mean \"never use dependencies\". That would be a childish conclusion. It means dependencies must become deliberate architectural choices again. They should earn their place through real complexity, real specialization, real maintenance value, or real domain expertise.
\nThey should not be the default answer to every small discomfort.
\nFor a long time, dependency-heavy development made economic sense. Writing everything in-house was expensive. Maintaining internal abstractions was expensive. Generating boilerplate was boring. Refactoring repeated patterns was slow. Documenting everything was painful. Testing every variation took time.
\nSo we outsourced complexity to frameworks and libraries. We accepted the dependency tax because the alternative was often slower, more expensive, and more fragile.
\nAI changes that equation, not because it magically produces perfect software, but because it changes the cost of producing certain categories of code.
\nStack Overflow's 2025 Developer Survey reports that 84% of respondents are using or planning to use AI tools, and 51% of professional developers use them daily. GitHub reported that nearly 80% of new developers on GitHub used Copilot within their first week in 2025. Controlled research on GitHub Copilot found that developers completed a JavaScript task 55.8% faster when using the tool.
\nThe picture is not universally simple. Other studies are more nuanced, and they should be. AI coding tools are more useful in some contexts than others, and generated code still requires strong human review, especially in complex systems, proprietary codebases, security-sensitive areas, and large multi-file changes.
\nBut the important point is not that AI writes perfect code. It does not.
\nThe important point is that AI makes boilerplate, repetitive implementation, documentation, test scaffolding, migration work, refactoring, API adaptation, pattern replication, simple feature assembly, and codebase navigation cheaper than they used to be.
\nThose are exactly the categories of work that made teams install many libraries in the first place.
\nIf a model can generate a project-specific implementation that follows your coding rules, passes your tests, respects your security constraints, uses your design tokens, and avoids unnecessary runtime dependencies, then the economics of abstraction change.
\nAt that point, the question is no longer only \"which package solves this?\"
\nThe better question becomes \"why should this be a package?\"
\nOne of the common misunderstandings about AI-generated software is that it will make standards less important. I think the opposite is true.
\nAI will make standards more valuable because models work better when the target is stable, documented, widely used, and well represented. Language standards, platform APIs, protocol specifications, accessibility rules, security practices, and explicit architectural constraints are model-friendly.
\nA framework is a moving target controlled by a smaller community. A standard is a wider agreement.
\nOn the web platform, we can already see this shift. Modern CSS is absorbing capabilities that once required preprocessors, JavaScript helpers, or framework-level conventions. Typed attr() lets CSS read attributes as typed values. CSS if() brings conditional logic into values. CSS custom functions aim to make reusable CSS logic native to the language.
\nWhen the platform learns these primitives, teams can use them directly only if their abstraction layers do not get in the way. Otherwise, the browser may already support the capability, but the product still has to wait for a framework, a library, a wrapper, a plugin, or a design system abstraction to catch up, expose it, document it, and stop fighting it.
\nThat is one ecosystem, but the principle is broader. When platforms become more expressive, and AI becomes better at producing code against stable standards, the value of non-standard abstraction decreases.
\nThe winning move is not to reject every framework. The winning move is to move as much product logic as possible toward stable, inspectable, standard primitives.
\nUse the language. Use the runtime. Use the platform. Use the framework when it still buys something real.
\nMany teams use frameworks as delivery mechanisms for best practices. The framework tells them how to organize files, fetch data, render pages, place state, compose UI, and decide which patterns are acceptable.
\nIn an AI-assisted workflow, many of those rules can move into configuration, automation, and project context.
\nCoding standards can become lint rules. Architecture decisions can become generation constraints. Design guidelines can become tokens and visual tests. Accessibility expectations can become automated checks. Security policies can become static analysis and dependency gates. Performance budgets can become CI failures. Reusable patterns can become agent skills. Project knowledge can become context the model can actually use.
\nThis is a major change because best practices stop being trapped inside framework conventions and become executable governance.
\nA convention helps when developers remember it. A rule enforces it. A test verifies it. An agent applies it repeatedly. A model generates code from it.
\nThat is the future shape of software abstraction. Not \"everyone must memorize the framework\", but \"the system knows the rules and keeps applying them\".
\nThe industry has spent years treating frameworks as identity. We say \"I am a React developer\", \"I am a Laravel developer\", \"I am a Rails developer\", \"I am a Spring developer\", \"I am a Django developer\", \"I am a Next developer\".
\nThis made sense when frameworks were the main interface between developers and complexity. But in an AI-native development environment, that identity becomes too small.
\nThe valuable skill will not be loyalty to a framework. The valuable skill will be understanding systems: language, runtime, platform, accessibility, security, performance, data, product constraints, and the way AI-generated work must be instructed, constrained, verified, and reviewed.
\nThe senior developer of the next era is not the person who knows the most framework APIs by memory. It is the person who can design the rules of the system so that humans and models can safely produce good software together.
\nThat requires more engineering, not less.
\nThis future is not no-code. No-code pretends complexity can disappear, and complexity does not disappear. It moves.
\nWhat changes is the layer where engineering work happens. Less time wiring borrowed abstractions, more time defining contracts. Less time adapting to framework churn, more time designing durable systems. Less time installing packages for trivial problems, more time making sure the generated solution is correct, accessible, secure, observable, and maintainable.
\nAI does not remove the need for senior engineers. It increases the need for them.
\nBecause when code becomes cheaper to produce, judgment becomes more valuable.
\n\"Vanilla\" does not mean naive. It does not mean writing everything from scratch forever. It does not mean refusing tools, frameworks, libraries, or ecosystems.
\nIt means preferring the native language, native runtime, and platform standards unless a dependency clearly earns its place.
\nA more vanilla world is not a world without abstraction. It is a world where abstraction is generated, governed, inspected, and owned. A world where dependencies are exceptions, not defaults. A world where libraries are chosen because they provide deep, hard, specialized value, not because nobody wanted to write twenty lines of code.
\nIt is a world where frameworks are useful tools, not architectural religions. A world where the model becomes part of the abstraction layer, but the output remains understandable, standard, testable, and close to the platform.
\nThis will not happen all at once. There will still be frameworks, libraries, ecosystems, and very good reasons to depend on external code. But the default is going to change.
\nThe age of installing an abstraction for every small discomfort is ending.
\nThe next era belongs to teams that can combine human judgment, platform standards, automated governance, and AI-generated implementation. Not because frameworks suddenly became useless, but because many of the reasons we needed them are being absorbed by something else.
\nThe model is becoming part of the abstraction. The platform is getting stronger. The dependency graph is becoming a liability.
\nAnd software teams are about to rediscover a very old idea: the best code is not the code you borrowed. It is the code you understand, control, verify, and can afford to change.
\nMost teams treat accessibility as a checklist at the end of a sprint. That approach misses the real problem. Accessibility is the baseline behavior of the interface under real user constraints.
\nThose constraints are not abstract. They are concrete:
\nIf the UI ignores those settings, it is not accessible, even when every button has a good label.
\n\"Responsive\" does not only mean breakpoints. It means the interface keeps working when conditions change. User preferences are one of those conditions.
\nA responsive interface should respond to:
\nDisplayPreferencesPopover exists to make that third point explicit and immediate.
On dout.dev, I wanted preference controls to be:
\nThe popover stores choices in localStorage, applies them on the root element, and keeps the page readable without a navigation detour.
<display-preferences-popover></display-preferences-popover>That single element exposes controls for motion, transparency, contrast, typography, and corner radius. The page reacts through CSS tokens and root data attributes, not through per-component hacks.
\nPeople with vestibular sensitivity, attention fatigue, or migraine triggers can be affected by excessive animation and blur. The component lets users reduce those effects directly.
\nTheme palettes can look \"clean\" and still fail readability in real conditions. A direct contrast preference gives users an immediate correction path.
\nNot everyone reads best with the same typeface and scale. Heading, body, and code stacks are adjustable because legibility is personal.
\nCorner radius is not only visual style. It affects edge detection and separation of interactive surfaces. Offering presets helps users pick what they parse faster.
\nThe point is not to provide infinite personalization. The point is to respect explicit user intent.
\nWhen a preference is set, the interface should obey it consistently:
\nThat is why the component writes stable state and the page consumes that state from shared tokens.
\nAccessibility starts before ARIA, before audits, and before tooling. It starts when the layout, motion, and text system respond to the person using the page.
\nDisplayPreferencesPopover exists to make that principle operational on every visit.
PixHighlighter begins with the smallest useful shape:
<pre is=\"pix-highlighter\" data-lang=\"js\"><code>const answer = 42;</code></pre>That is still a real pre element with a real code child. The source is readable before JavaScript runs, copyable as text, and understandable to assistive technology. The component does not need a custom shadow tree to make code look like code.
The important decision is what it refuses to do by default: the primary path does not wrap every token in markup. The code block is not a pile of span wrappers. It is one text node that can be painted by the browser.
\nEach lexer under src/scripts/components/PixHighlighter/Lexers/ walks the source and emits ranges:
{ type: 'kw', start: 0, end: 5 }That object says \"the characters from 0 to 5 are a keyword.\" It does not say \"insert a span here.\" Parsing and rendering stay separate. The same token stream can power the modern renderer, the fallback renderer, tests, and any future diagnostics without changing the source model.
\nLanguage aliases are normalized before lookup. javascript becomes js, typescript becomes ts, shell and zsh become bash, and empty language values fall back to js. Content authors get a forgiving interface; the renderer gets one clean language key.
The best version of PixHighlighter uses the CSS Custom Highlight API. When CSS.highlights and Highlight exist, the component creates DOM Range objects for each token and stores them in named highlight registries:
const highlight = new Highlight(range);\nCSS.highlights.set('pix-kw', highlight);CSS then styles those names directly:
\n::highlight(pix-kw) {\n color: var(--pix-highlighter--kw);\n}That is the whole trick. The browser paints a range of text without changing the text into markup. Selection stays clean. Copy stays clean. The DOM stays quiet. Themes remain normal CSS variables instead of a second token system hidden inside generated spans.
\nThe rule is simple: fallback spans only when the Highlight API is unavailable. In that case, the component maps the same token ranges to conservative markup:
\n<span data-token=\"kw\">const</span>The fallback is not a different highlighter. It is the same lexer output rendered into older browser primitives. The CSS already has matching rules for [data-token='kw'], [data-token='str'], and the rest of the token types, so the visual result remains close without forcing modern browsers to carry extra DOM.
The component imports its CSS with bundle-text:. That bundle includes the base component stylesheet plus the theme files.
At runtime, ensureComponentStyles() prefers document.adoptedStyleSheets. If constructable stylesheets are available, one CSSStyleSheet is created and shared by every instance. If not, the component injects one managed <style data-styles> element.
Ten code blocks still get one style payload. The component can appear throughout an article without multiplying its CSS.
\nEvery instance renders a compact toolbar with copy and theme controls. The picker appears per block, but the selected theme is page-wide state. PixHighlighter.applyTheme() writes the value to document.documentElement.dataset.pixHighlighterTheme, persists it in localStorage, and syncs every active instance.
That avoids a page where one snippet is using one palette and the next snippet is using another because of local component state. Code theme is a reading preference, so the page owns it.
\nThe menu also uses progressive layout. CSS anchor positioning handles the clean path. When the browser lacks it, the component measures the trigger and keeps the list inside the viewport with fixed coordinates.
\nThe copy button reads code.textContent. It does not inspect highlight ranges, fallback spans, toolbar state, or theme state. Highlighting is visual; the source text is the contract.
If the Clipboard API is available, the component calls navigator.clipboard.writeText(). If that path fails, it falls back to a temporary textarea and document.execCommand('copy'). The UI states are intentionally small: idle, copied, or error, each with an accessible label.
PixHighlighter is built for a static editorial site: short examples, no frontend framework, no runtime highlighter dependency, and a design system that already owns typography, color, and motion.
The architecture works because each layer has one job:
\nThat is the pattern I want here: ordinary HTML first, modern browser APIs where they remove markup, and a fallback that preserves the same source text instead of inventing a second content model.
\n", "image": "https://dout.dev/assets/og/posts/2026-06-13-how-pixhighlighter-is-built.png", "date_published": "2026-06-13T00:00:00.000Z", "tags": [ "Vanilla-js", "Frontend", "Architecture" ] }, { "id": "https://dout.dev/posts/2026-06-09-wcag-22-aa-without-aria-spam.html", "url": "https://dout.dev/posts/2026-06-09-wcag-22-aa-without-aria-spam.html", "title": "WCAG 2.2 AA Without ARIA-Spam: Landmarks, Heading Order, Skip-Links", "summary": "The unpopular opinion", "content_html": "Most accessibility failures I see in production are not missing features. They are HTML that was never semantic, covered in ARIA attributes that were supposed to fix the damage. That approach is a tax forever. ARIA is a powerful tool and also a trap: the first rule of ARIA is to not use it if a native element would do the job.
\nFor dout.dev I made a rule for myself. Every page starts as semantic HTML. ARIA only shows up when there is no native alternative. That rule covered most of the WCAG 2.2 AA checklist before I wrote a single aria-* attribute.
HTML5 already gives you landmarks. A screen reader or a \"Rotor\" in VoiceOver reads them as navigation regions. You do not need to annotate them.
\n<body>\n <a class=\"skip-link\" href=\"#main\">Skip to content</a>\n\n <header>\n <nav aria-label=\"Primary\">\n <a href=\"/\">dout.dev</a>\n <ul>\n <li><a href=\"/archive.html\">Archive</a></li>\n <li><a href=\"/about.html\">About</a></li>\n </ul>\n </nav>\n </header>\n\n <main id=\"main\">\n <article>\n <h1>Post title</h1>\n <p>...</p>\n </article>\n </main>\n\n <footer>\n <p>© 2026 dout.dev</p>\n </footer>\n</body>No role=\"banner\", no role=\"main\", no role=\"navigation\". Each element announces itself. The only ARIA attribute here is aria-label=\"Primary\" on the nav, because the page has more than one nav element and screen reader users benefit from knowing which is which.
Heading order is one of the WCAG 2.2 success criteria most sites fail silently. The rule: each page has one h1, and subsequent headings go down the tree in order - h2, then h3, never skipping.
On dout.dev, the post layout enforces it. The post title is always h1. Section headings in the markdown body start at h2. The post generator validates the tree at build time; if a post starts with ###, the build fails.
<!-- Good -->\n\n# Post title\n\n## Section\n\n### Subsection\n\n## Another section\n\n<!-- Bad, the build rejects this -->\n\n# Post title\n\n#### OopsKeyboard users who arrive on a page need a way to jump to the main content without tabbing through the entire header. The skip-link is hidden visually until it receives focus, at which point it appears and announces itself.
\n.skip-link {\n position: absolute;\n inset-inline-start: 0;\n inset-block-start: 0;\n transform: translateY(-100%);\n transition: transform 0.15s;\n}\n\n.skip-link:focus-visible {\n transform: translateY(0);\n}The first keyboard tap on the page reveals it. Screen reader users hear it immediately regardless of visibility.
\nBrowsers removed default focus styles from buttons in some contexts and left designers to reinvent them. The result is sites where keyboard users cannot see where they are. The WCAG 2.2 addition 2.4.11 Focus Not Obscured codifies how visible focus must be.
:focus-visible {\n outline: var(--focus-ring);\n outline-offset: 2px;\n border-radius: var(--radius-1);\n}:focus-visible shows the ring only for keyboard navigation, not for mouse clicks. That keeps the design calm for pointer users and explicit for keyboard users.
Contrast is mathematical. You either meet the ratio or you do not. WCAG 2.2 AA requires 4.5:1 for body text, 3:1 for large text. I check every token pair against the requirement when the theme is defined, and I do not ship colors that fail.
\nA cheap way to keep yourself honest is to wire a contrast check into the build, so the CI fails if a semantic token combination drops below threshold. That is mechanical, not creative, and it pays back every time a designer-in-you wants to pick a \"softer\" foreground color.
\nARIA is not evil. It shines when native HTML genuinely does not cover what you are building:
\naria-live=\"polite\" on the search results summary, so that changes in result count are announced without stealing focus;aria-current=\"page\" on the current pagination link;aria-expanded on a disclosure button that toggles a panel;aria-describedby to associate an error message with the input it describes.All of these are cases where a sighted user has a visual cue that non-sighted users would miss. ARIA fills the gap.
\naria-label on an icon that already has accessible text nearby.role=\"button\" on a <button>.aria-hidden=\"true\" on decorative icons that were inside a labeled parent - <span aria-hidden=\"true\"> on a pure SVG icon is fine; on a structural element it is a bug.ARIA without a reason is noise for screen readers and maintenance for you.
\nWCAG 2.2 AA is not a ceiling. It is a baseline, and most of it is achievable with semantic HTML, visible focus, proper heading order, and a skip-link. Start there. Add ARIA last, with intent.
\n:focus-visible - MDNFor about ten years, serious frontend work leaned on tooling that papered over missing CSS features: Sass for nesting, Styled Components for dynamic theming, BEM conventions for scoping, utility frameworks for constraint. Most of those reasons quietly disappeared in the last two browser cycles. Modern CSS has container queries, native nesting, :has(), cascade layers, logical properties, color-mix(), clamp(), and more. On dout.dev I ship all of these, and the CSS is shorter than it would have been five years ago.
This post is not \"CSS is cool now.\" It is a walk through specific modern features that let me delete a preprocessor and a handful of conventions.
\nMedia queries size components against the viewport. That is the wrong reference frame for components that can appear in a full-width article or a narrow sidebar. Container queries fix it.
\n.post-card {\n container-type: inline-size;\n container-name: card;\n}\n\n@container card (min-width: 30rem) {\n .post-card__layout {\n display: grid;\n grid-template-columns: 10rem 1fr;\n gap: var(--space-5);\n }\n}The card adapts to its container, not the page. You drop it in any layout and it behaves. I removed a half-dozen component-level media queries when I moved to container queries, and I have not missed them.
\nNative CSS nesting lets you keep related rules together without compiling:
\n.post-card {\n padding: var(--space-5);\n background: var(--color-bg-raised);\n\n & h2 {\n font-size: var(--text-xl);\n line-height: var(--font-lineheight-2);\n }\n\n &:hover {\n transform: translateY(-2px);\n }\n\n @media (prefers-reduced-motion: reduce) {\n &:hover {\n transform: none;\n }\n }\n}The only gotcha is the & for selectors that would otherwise concatenate ambiguously. It is a small price to pay for deleting the Sass build step. Baseline support is wide; check current status on caniuse if you need to be sure.
:has() for parent-aware styling:has() is the feature CSS was missing for twenty years. \"Style the parent based on the child\" is now a one-liner:
/* Collapse the sidebar when the article has no table of contents */\n.post-layout:has(.outline[hidden]) {\n grid-template-columns: 1fr;\n}\n\n/* Highlight figures that contain a caption */\nfigure:has(figcaption) {\n border-inline-start: 3px solid var(--color-accent);\n padding-inline-start: var(--space-4);\n}Anywhere I used to reach for JavaScript to toggle a parent class based on child state, :has() does it in the cascade. Less code, no flash of incorrect styling.
If you care about bidirectional text, or you just want your CSS to stop lying about what it does, logical properties are non-negotiable. Instead of margin-left and padding-right, you write margin-inline-start and padding-inline-end. The effect is the same in English and correct in Arabic.
.callout {\n padding-inline: var(--space-5);\n padding-block: var(--space-4);\n border-inline-start: 3px solid var(--color-accent);\n}Even in an English-only site like dout.dev, using logical properties is better hygiene. It documents intent, and it makes the CSS future-proof if the site ever goes multilingual.
\ncolor-mix() and clamp() for token derivationTwo small features that replace a lot of Sass math.
\n:root {\n --color-accent: #ff6b3d;\n --color-accent-soft: color-mix(in oklch, var(--color-accent) 20%, var(--color-bg));\n}\n\nh1 {\n /* Responsive type without media queries */\n font-size: clamp(1.875rem, 1.4rem + 2vw, 3rem);\n}color-mix() lets you derive shades from semantic tokens at runtime, so theme changes cascade into every derived value. clamp() handles fluid type without a script.
On a small project, layering is overkill. On any project with an external reset, a design system, and component-level overrides, cascade layers save you from specificity wars.
\n@layer reset, tokens, base, components, utilities;\n\n@layer reset {\n /* modern-normalize or similar */\n}\n\n@layer components {\n .post-card {\n /* ... */\n }\n}The layer order determines which rules win, regardless of specificity. I use it as a safety net, not as a crutch. Most rules still work fine without thinking about it.
\nIf you last wrote CSS seriously three years ago, the landscape is different. Container queries alone are worth a re-evaluation of your conventions. :has() kills a whole class of JavaScript hacks. Native nesting and layers kill the preprocessor. Ship what the browser already gives you.
:has() selector - MDN\"Vibe coding\" has become shorthand for \"let the AI write whatever it wants and see what happens.\" That is not what I did on dout.dev, and it is not what the term should mean if it is going to be useful. The version I work with looks more like this:
\n\n\nVibe coding is driving an AI copilot hard with clear intent, small units of work, and strict review, while keeping the architectural decisions in your own head.
\n
The vibe is the speed. The rigor is the review. This post is the workflow that made 19 milestones shippable without the repo turning into a science fair.
\nEvery session had one outcome. \"Wire up the RSS feed.\" \"Add the skip-link.\" \"Extract the pagination component.\" Not \"improve the site.\" Not \"make it more accessible.\" The outcome fit in one commit.
\nThat discipline mattered more than the prompt engineering. When a session has a scoped outcome, the copilot's proposals can be evaluated against a clear question: did this produce the outcome, and is the diff small? When a session is open-ended, every proposal feels plausible, and you accept changes you later regret.
\nThree parts, in this order.
\nState the goal and the constraint in one paragraph. Not a task list. A paragraph that a smart colleague could act on cold. \"I am adding a tag archive generator. It should produce /tags/<slug>.html for page 1 and /tags/<slug>/<n>/ for subsequent pages. Must match the existing pagination contract. Do not touch the post template.\"
Point at the files that matter. \"Read scripts/cms/page-generator.js and src/components/pagination.html. Mirror their conventions.\" Explicit pointers beat the copilot's guess about what is relevant.
Name the done-state. \"Return the new file and the minimal diff to wire it up. Do not reformat unrelated code.\" Stating the shape of the output up front cuts down on scope creep.
\nThat pattern saved me hours. The ones I got wrong were the ones where I vibed the prompt itself.
\nMechanical edits, exploratory scaffolding, documentation stubs, test harnesses, draft implementations I intended to rewrite. Roughly: anything where \"a reasonable first version\" had obvious shape and I wanted the time back.
\nA concrete example. The OG image generator needed 12 SVG templates for the various card states. Each was a small variation on the next. I described the first one, had the copilot produce it, reviewed, then asked for the remaining 11 with specific variations. That would have been an hour of tedium; it was ten minutes.
\naria-current, when to rely on semantic HTML, how to test with a screen reader.The last rule is the one that keeps the copilot from becoming technical debt generator.
\nEvery diff got read line by line. Not \"skimmed.\" Read. That is the work the copilot cannot do for you, and skipping it is how you end up with patterns that drift from the rest of the codebase.
\nThree review questions:
\nAsking for simpler versions is the single highest-leverage feedback I give the copilot. \"Make this boring.\" \"Remove the try/catch.\" \"This function does not need options.\" Boring is a feature.
\n// Fetch the user data from the server above fetchUser(). Useless. I strip them on sight.None of these are deal-breakers. They are the shape of what the copilot tends to produce when under-specified.
\nEach of the 19 milestones had a short document with the exit checklist. When the checklist was green, the milestone closed and I moved on. That structure, more than anything, kept the overall scope honest.
\nThe alternative - a single rolling backlog with no exit criteria - is how personal projects stall. Without milestones I would have still been \"polishing\" after three months and not shipped the blog.
\nTwo things I will keep after this project.
\nMost of my hesitation is not about the hard choice. It is about the tedium of implementing the choice. Delegating the tedium compresses the space between \"I know what to do\" and \"it is done.\" That is not laziness; it is leverage.
\nI am more opinionated than I thought. When the copilot proposed something generic, I rejected it because it did not match the project's taste. I had to learn to articulate that taste explicitly - in prompts, in code comments, in README rules. Writing those articulations made the project more coherent.
\nVibe coding done well is not \"let the AI drive.\" It is \"drive harder, with better brakes.\" Small units of work, clear prompts, strict review, and a list of things you will never delegate. Hold that line and the copilot is a force multiplier. Drop it and you are doing unpaid editing for a confident junior engineer.
\nGitHub Pages is excellent for serving a static site. It is also, by default, missing two features that Netlify and Vercel have made everyone expect: deploy previews on pull requests, and one-click rollback to a previous deploy.
\nNeither is actually missing. They are just not turned on. The pieces exist in GitHub Actions; you have to wire them up. On dout.dev, that wiring is about 40 lines of YAML and one simple naming convention.
\nProduction deploys run from main or from workflow_dispatch. The workflow has two jobs - build and deploy - and produces a site at https://dout.dev.
name: Deploy Pages\n\non:\n push:\n branches: [main]\n workflow_dispatch:\n\npermissions:\n contents: read\n pages: write\n id-token: write\n\nconcurrency:\n group: pages\n cancel-in-progress: true\n\njobs:\n build:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: actions/configure-pages@v5\n - uses: pnpm/action-setup@v4\n with: { version: 10.33.0 }\n - uses: actions/setup-node@v4\n with: { node-version: 24, cache: pnpm }\n - run: pnpm install --frozen-lockfile\n - run: pnpm build\n - uses: actions/upload-pages-artifact@v3\n with: { path: dist }\n\n deploy:\n needs: build\n runs-on: ubuntu-latest\n environment:\n name: github-pages\n url: DEPLOYMENT_PAGE_URL\n steps:\n - uses: actions/deploy-pages@v4\n id: deploymentThat is a complete Pages workflow. The concurrency group prevents two overlapping deploys from fighting. The environment: github-pages line is required for the Pages deployment to succeed and also records deploy history.
GitHub Pages has one \"live\" site per repository. You cannot deploy a PR to a live preview URL the way Netlify does.
\nWhat you can do: build the PR, upload the dist/ as an artifact, and comment on the PR with a link to download it. A reviewer can extract the zip locally and open it. For a single-author blog, that is often enough.
name: PR Build\n\non:\n pull_request:\n branches: [main]\n\njobs:\n build:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: pnpm/action-setup@v4\n with: { version: 10.33.0 }\n - uses: actions/setup-node@v4\n with: { node-version: 24, cache: pnpm }\n - run: pnpm install --frozen-lockfile\n - run: pnpm build\n\n - uses: actions/upload-artifact@v4\n with:\n name: dist-PR_NUMBER\n path: dist\n retention-days: 14The artifact is named with the PR number, so CI history stays navigable. Retention is two weeks - long enough to review, short enough to not accumulate forever.
\nFor reviewers who want a clickable URL rather than a zip, there is a second pattern: a separate repository that hosts \"preview\" deploys at URLs like preview-123.dout.dev.
The CI workflow pushes the PR's dist/ into a subdirectory of the preview repo's main branch, and the preview site is configured to serve those subdirectories. A bot comments on the PR with the preview URL.
This is more setup than most personal projects need. For dout.dev I use the zip-artifact pattern. For a team project, I would build the separate-repo preview pipeline.
\nThis is the feature I use more often than I expected.
\nWhen a bad deploy reaches production - wrong content, broken CSP, accidentally unpublished post - the recovery path is:
\nThat rebuilds the old commit and redeploys it. One minute from \"oh no\" to \"fixed.\"
\nThe prerequisites:
\nmain. No manual artifact uploads. Every deploy is reproducible from a specific SHA.The workflow at the top of this post satisfies both. That is why it rolls back cleanly.
\nA useful side effect of \"every deploy is a commit\" is that the Actions history is the deploy history. You can see which commit is live right now, which commits have been deployed before, and how long each deploy took.
\nThe Pages environment in the repo settings also tracks \"Active deployment\" and shows the deployed commit SHA at the top. If you have to answer \"what is live right now?\" for a coworker, that screen is the authoritative source.
\nGitHub Pages with GitHub Actions is a complete deploy pipeline, including previews and rollback, if you accept that previews come as artifacts rather than live URLs. For most personal projects that is the right trade-off - no third-party service, no extra auth, and the same UI you are already using for the repo.
\nactions/deploy-pagesactions/upload-artifactA single-author blog does not need CI the way a team product does. But any site that accepts drive-by contributions, or any site that I want to be able to touch in six months without re-learning, benefits from a gate that answers one question at merge time:
\n\n\nDoes this change still produce a correct, accessible, valid site?
\n
The gate on dout.dev is a single command, pnpm quality:check, that runs the same checks locally and in GitHub Actions. If it is green, the site is publishable. If it is red, it tells me which layer broke.
pnpm test\npnpm spellcheck\npnpm format:check\npnpm format:check:html\npnpm validate:allFive commands, each doing one thing.
\npnpm test - Node's built-in test runner on the CMS and template-engine code. Fast. No Jest, no Vitest, no configuration surface.
pnpm spellcheck - cspell against the markdown and HTML files. Catches typos in posts and navigation labels before they reach the reader.
pnpm format:check - Biome in check mode over JavaScript. Enforces the single formatter.
pnpm format:check:html - Prettier in check mode over HTML templates. HTML formatting is one of those things everyone forgets to verify until a diff becomes impossible to review.
pnpm validate:all - a composite of HTML validation, structural validation, link checking, and accessibility validation. The one that catches the most real bugs.
HTML validation is underrated. Bad nesting, missing alt text, heading skips, unused IDs - all of these slip past manual review and all of them matter. The validator on dout.dev runs against every file under src/ and dist/ and reports problems with file and line.
import { readFileSync } from 'node:fs';\nimport { HTMLHint } from 'htmlhint';\n\nfunction validateHtml(file) {\n const rules = {\n 'doctype-first': true,\n 'tag-pair': true,\n 'attr-lowercase': true,\n 'attr-value-double-quotes': true,\n 'alt-require': true,\n 'id-unique': true,\n 'title-require': true,\n };\n const source = readFileSync(file, 'utf8');\n return HTMLHint.verify(source, rules);\n}HTMLHint is not the only option. @linthtml/linthtml is similar. For deep validation the W3C Nu Validator is authoritative. For this project HTMLHint is enough.
Every internal link on the site gets resolved to an actual file at build time. A broken link in a post or in the navigation fails the build.
\nfunction validateLinks(dir) {\n const failures = [];\n for (const file of walk(dir)) {\n const html = readFileSync(file, 'utf8');\n for (const href of extractHrefs(html)) {\n if (isInternal(href) && !exists(resolveToFile(href))) {\n failures.push({ file, href });\n }\n }\n }\n return failures;\n}External links are checked only occasionally, not on every build, because network flakiness should not fail a PR. A scheduled task runs external-link validation once a week.
\nThe a11y check runs axe-core over every generated page, using Playwright as the headless browser. It catches a significant fraction of WCAG issues automatically - missing labels, insufficient contrast, heading order problems, keyboard trap candidates.
\nimport { test, expect } from '@playwright/test';\nimport { injectAxe, checkA11y } from '@axe-core/playwright';\n\ntest('posts pass axe', async ({ page }) => {\n await page.goto('/posts/2026-06-09-wcag-22-aa-without-aria-spam.html');\n await injectAxe(page);\n await checkA11y(page, null, {\n detailedReport: true,\n detailedReportOptions: { html: true },\n });\n});Axe does not catch everything. Nothing does. What it catches is the base rate of failures that keep creeping in through drive-by edits.
\nEarly in the project, I shipped a build with a broken CSP meta tag. The page rendered; the browser silently refused to load the JavaScript. The fix is a build-time check that verifies the generated CSP is well-formed and covers the scripts referenced in the HTML.
\nfunction validateCsp(html) {\n const csp = extractCspMeta(html);\n const scripts = extractInlineAndExternalScripts(html);\n const violations = scripts.filter((s) => !cspAllows(csp, s));\n return violations;\n}This is the kind of check you write exactly once, after exactly one production incident.
\nAll of this is wired in .github/workflows/deploy-pages.yml as a single step:
- name: Build site\n run: pnpm build\n\n- name: Quality gate\n run: pnpm quality:checkLocally I run pnpm quality:check before any push. If I am about to merge something significant, I also run pnpm test:visual - the Playwright visual regression suite - which is slower and therefore not on the default path.
A quality gate is a contract with your future self. Write it once, keep it small, run it everywhere. The specific checks that matter depend on the project. For a static editorial site, HTML validity, link integrity, and axe-core accessibility cover most of what goes wrong.
\n\"SEO\" is a category name. Inside it are a dozen unrelated concerns, some of which matter for most sites and many of which do not. This post is the handful of tags I ship on dout.dev because they demonstrably help crawlers and discovery, and the handful I do not ship because they are noise.
\nThe line I draw: a tag earns its place if a major crawler uses it or if it improves a demonstrable discovery behavior. If it is \"recommended\" but nobody can point to the behavior it improves, I leave it out.
\nEvery page on dout.dev has a canonical URL in the head.
\n<link rel=\"canonical\" href=\"https://dout.dev/posts/2026-10-13-canonical-structured-data-hreflang.html\" />The value is the absolute URL of the page as it lives on the site. Three rules:
\nWhere canonical matters most is when the same content is reachable via multiple URLs. Pagination is the classic case: /tags/accessibility/2/ should still canonical to itself, not to /tags/accessibility/. Search result pages, query-string variations, and session-id URLs are the other common cases.
On a clean static site with one URL per page, canonical is mostly boilerplate. It is still worth shipping, because the day a duplicate URL appears (through a short-link service, a Mastodon share, a paginated archive), the canonical is the difference between a clean index and content fragmentation.
\nJSON-LD is the format Google, Bing, and LinkedIn want for structured data. It is a <script type=\"application/ld+json\"> block in the head.
<script type=\"application/ld+json\">\n {\n \"@context\": \"https://schema.org\",\n \"@type\": \"BlogPosting\",\n \"headline\": \"Canonical, Structured Data, Hreflang: SEO Without Cargo Culting\",\n \"description\": \"The SEO tags that actually do work on a static blog...\",\n \"datePublished\": \"2026-10-13\",\n \"author\": {\n \"@type\": \"Person\",\n \"name\": \"Emiliano \\\"pixu1980\\\" Pisu\",\n \"url\": \"https://dout.dev/about.html\"\n },\n \"image\": \"https://dout.dev/assets/og/posts/2026-10-13-canonical-structured-data-hreflang.png\",\n \"publisher\": {\n \"@type\": \"Organization\",\n \"name\": \"dout.dev\",\n \"url\": \"https://dout.dev\"\n },\n \"mainEntityOfPage\": {\n \"@type\": \"WebPage\",\n \"@id\": \"https://dout.dev/posts/2026-10-13-canonical-structured-data-hreflang.html\"\n }\n }\n</script>That block earns its place because:
\nThe post generator emits this block from the normalized post record. One source, per-post substitution, no manual upkeep.
\nWebSite with SiteNavigationElement, BreadcrumbList on posts that have no breadcrumb UI, Article alongside BlogPosting, @type schemas for which no consumer has a documented behavior.
The heuristic: if I cannot point at a concrete consumer behavior, I do not ship the schema. \"Might help ranking someday\" is not a reason. Schema spam has a negative cost with some crawlers, which explicitly penalize sites that dump irrelevant structured data.
\nhreflang tells crawlers which language a page is in and what the equivalents are in other languages.
<link rel=\"alternate\" hreflang=\"en-US\" href=\"https://dout.dev/posts/...\" />\n<link rel=\"alternate\" hreflang=\"it-IT\" href=\"https://dout.dev/it/posts/...\" />\n<link rel=\"alternate\" hreflang=\"x-default\" href=\"https://dout.dev/posts/...\" />dout.dev is English only. The roadmap removed the i18n milestone. So hreflang is a no-op for my case and I do not ship it. Writing it out here for completeness: the moment a site has localized content, hreflang is non-optional, and omitting it is a real SEO hit.
\nThe x-default row is the one most people miss. It tells crawlers which URL to serve when no language matches. Without it, a user on a Swahili browser with no Swahili translation gets the first-listed alternate, which may or may not be what you want.
These are not strictly SEO, but they are discovery. Every post has:
\n<meta property=\"og:site_name\" content=\"dout.dev\" />\n<meta property=\"og:type\" content=\"article\" />\n<meta property=\"og:title\" content=\"...\" />\n<meta property=\"og:description\" content=\"...\" />\n<meta property=\"og:url\" content=\"...\" />\n<meta property=\"og:image\" content=\"...\" />\n<meta property=\"og:image:width\" content=\"1200\" />\n<meta property=\"og:image:height\" content=\"630\" />\n<meta property=\"og:locale\" content=\"en_US\" />\n<meta property=\"article:published_time\" content=\"2026-10-13\" />\n\n<meta name=\"twitter:card\" content=\"summary_large_image\" />The og:image:width and og:image:height are not optional in practice; Mastodon's preview system, in particular, falls back to a smaller thumbnail without them.
twitter:card is one of the rare \"Twitter-specific\" tags still worth shipping. Once set, both Twitter and X parse it reliably; omitting it sometimes degrades the card to a small summary.
<meta name=\"robots\" content=\"index,follow\" /> <meta name=\"referrer\" content=\"strict-origin-when-cross-origin\" />robots is explicit by default on the posts; the home page and archive have the same value. Drafts (published: false) never render, so there is no need for a noindex path for them.
referrer is a privacy choice. It tells the browser how much referrer information to send when the user clicks a link off-site. strict-origin-when-cross-origin is the reasonable default: same-origin gets the full URL, cross-origin gets only the origin, and HTTP→HTTPS downgrade suppresses it entirely.
Two findings from the first months after publishing.
\nCanonical works, but only after the crawler re-crawls. A short-link that 301s to your canonical URL may still show up in Search Console as a separate URL for days before it merges. The canonical is correct; the crawl index is eventually consistent.
\nStructured data errors are loud. Google Search Console pings you within days if the JSON-LD is malformed. Fixing it is a round trip; the build-time validation is worth adding so errors are caught before deploy.
\nSEO on a blog is not magic. Three tags - canonical, structured data, Open Graph - cover most of the actual behavior. Hreflang only when you have multiple languages. Skip the dozens of \"recommended\" tags unless you can point at the consumer behavior they enable. The goal is a clean, honest document, not a holiday tree of meta tags.
\nEvery post needs a social preview image - the card that appears when someone shares the URL on Slack, Twitter, or LinkedIn. The options usually break down like this.
\nog.dev/render?title=... produces an image on demand. Works. Adds a third-party dependency, latency, and a potential point of failure.For dout.dev I went build-time, for one reason: I wanted the image to be a byproduct of the build, cacheable as a static file, with zero runtime dependency. The implementation is about 150 lines of Node.
\nThe trick is that OG images are rasterized SVGs. SVG is a markup language I can generate with the same template engine as the rest of the site. Sharp then converts the SVG to PNG at 1200×630, which is the OG card spec.
\n<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"1200\" height=\"630\" viewBox=\"0 0 1200 630\">\n <rect width=\"1200\" height=\"630\" fill=\"#0b0b0f\" />\n\n <text x=\"80\" y=\"180\" font-family=\"Inter, sans-serif\" font-size=\"24\" fill=\"#ff6b3d\"\n font-weight=\"600\" letter-spacing=\"0.08em\">DOUT.DEV</text>\n\n <text x=\"80\" y=\"320\" font-family=\"Inter, sans-serif\" font-size=\"64\" fill=\"#e7e7ef\"\n font-weight=\"700\" style=\"line-height: 1.1\">\n <tspan x=\"80\" dy=\"0\">OG Images at Build Time</tspan>\n <tspan x=\"80\" dy=\"80\">SVG + Sharp in 150 Lines</tspan>\n </text>\n\n <text x=\"80\" y=\"540\" font-family=\"Inter, sans-serif\" font-size=\"24\" fill=\"#a0a0b4\">\n by Emiliano \"pixu1980\" Pisu · 11 Aug 2026\n </text>\n</svg>That template has variables where the title, date, and author go. The generator produces one per post.
\nThe hardest single problem in OG image generation is fitting a variable-length title inside a fixed-width box without it running off the edge.
\nThe brute-force solution - \"measure the text, wrap manually\" - requires a font metrics library. The simpler solution - greedy wrapping with a conservative line-length budget - is what I use.
\nfunction wrapTitle(title, maxChars = 26) {\n const words = title.split(/\\s+/);\n const lines = [];\n let current = '';\n for (const word of words) {\n if ((current + ' ' + word).trim().length > maxChars) {\n lines.push(current);\n current = word;\n } else {\n current = (current + ' ' + word).trim();\n }\n }\n if (current) lines.push(current);\n return lines.slice(0, 3);\n}26 characters is an empirical value for Inter at 64px in a 1040px box with 80px margins. I tuned it once, compared against the longest real titles, and moved on. The generator truncates to three lines because four looks cramped.
\nSharp handles the SVG-to-PNG conversion. It is a one-liner with reasonable defaults.
\nimport sharp from 'sharp';\n\nasync function renderOg(svg, outputPath) {\n await sharp(Buffer.from(svg)).resize(1200, 630).png({ compressionLevel: 9 }).toFile(outputPath);\n}compressionLevel: 9 squeezes the PNG a bit at the cost of build time. On a small blog the total is under a second per image, so it is worth it.
import { readFileSync } from 'node:fs';\nimport sharp from 'sharp';\n\nconst template = readFileSync('src/og-template.svg', 'utf8');\n\nexport async function generateOgImage(post, outputPath) {\n const lines = wrapTitle(post.title);\n const titleSvg = lines.map((line, i) => `<tspan x=\"80\" dy=\"${i === 0 ? 0 : 80}\">${escapeXml(line)}</tspan>`).join('');\n\n const svg = template\n .replace('<title-placeholder>', titleSvg)\n .replace('<date-placeholder>', formatDate(post.date))\n .replace('<author-placeholder>', 'Emiliano "pixu1980" Pisu');\n\n await sharp(Buffer.from(svg)).png({ compressionLevel: 9 }).toFile(outputPath);\n}150 lines with the helpers included. No fonts-as-files wizardry. No headless browser. No Puppeteer.
\nSVG font-family=\"Inter\" only works if the system rendering the SVG has Inter installed, which is not the case on GitHub Actions runners.
Two paths:
\nOn dout.dev I went with option 2: a GitHub Actions step installs Inter before the build runs. That keeps the SVG clean.
\n- name: Install Inter font\n run: |\n wget -q https://fonts.google.com/download?family=Inter -O inter.zip\n unzip -q inter.zip -d /usr/share/fonts/inter\n fc-cache -fThe URL for Google Fonts bulk download is stable enough; if it breaks, I self-host the .ttf in the repo.
One PNG per post, under src/assets/og/posts/<slug>.png. The CMS also generates month OG images under src/assets/og/months/ and writes a manifest at src/assets/og/manifest.json so other build steps can reference them.
The post template references the image in the <head>:
<meta property=\"og:image\" content=\"https://dout.dev/assets/og/posts/2026-08-11-og-images-at-build-time.png\" />\n<meta property=\"og:image:width\" content=\"1200\" />\n<meta property=\"og:image:height\" content=\"630\" />\n<meta name=\"twitter:card\" content=\"summary_large_image\" />og:image:width and og:image:height are not required, but many crawlers check them and Mastodon's preview service will happily show a tiny image if dimensions are missing.
You do not need a runtime OG service, a headless browser, or a third-party API. A templated SVG, a wrapping function, and Sharp cover the whole problem in 150 lines. It runs at build time, commits to dist/, and costs nothing after the first build.
A blog that does not ship feeds and a sitemap is a blog that nobody can reliably subscribe to, and a blog that crawlers have to guess at. Both problems are fixed with three files:
\nfeed.rss for classic RSS readers;feed.json for modern readers that prefer JSON Feed;sitemap.xml for crawlers.On dout.dev all three are generated at build time from the same normalized dataset the page generator uses. No external tooling. No runtime hit.
\nDespite being old, RSS remains the format that every reader supports. If you ship exactly one feed, ship RSS. The schema is tiny and the templating is a for-loop.
\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<rss version=\"2.0\" xmlns:atom=\"http://www.w3.org/2005/Atom\">\n <channel>\n <title>dout.dev</title>\n <link>https://dout.dev</link>\n <description>Vanilla-first static blog on web standards and AI-assisted engineering.</description>\n <language>en-us</language>\n <lastBuildDate>Mon, 30 Jun 2026 08:00:00 GMT</lastBuildDate>\n <atom:link href=\"https://dout.dev/feed.rss\" rel=\"self\" type=\"application/rss+xml\" />\n\n <item>\n <title>RSS + JSON Feed + Sitemap at Build Time</title>\n <link>https://dout.dev/posts/2026-06-30-rss-json-feed-sitemap-at-build-time.html</link>\n <guid isPermaLink=\"true\">https://dout.dev/posts/2026-06-30-rss-json-feed-sitemap-at-build-time.html</guid>\n <pubDate>Tue, 30 Jun 2026 08:00:00 GMT</pubDate>\n <description><![CDATA[The three distribution files every blog should ship...]]></description>\n </item>\n </channel>\n</rss>Two things are easy to get wrong here.
\nThe lastBuildDate and pubDate must be RFC 822. Not ISO. Not \"a date.\" RFC 822 with a four-digit year is the correct shape. Readers will silently drop items that do not parse.
The <atom:link rel=\"self\"> is not optional. It is the self-reference that tells aggregators where the feed lives. Some validators treat it as a warning; some treat it as a bug; some readers ignore it. Ship it.
JSON Feed is worth shipping alongside RSS. The format is human-readable, trivial to parse, and the spec is under one screen. Readers like NetNewsWire and Readwise speak it natively.
\n{\n \"version\": \"https://jsonfeed.org/version/1.1\",\n \"title\": \"dout.dev\",\n \"home_page_url\": \"https://dout.dev\",\n \"feed_url\": \"https://dout.dev/feed.json\",\n \"language\": \"en-US\",\n \"items\": [\n {\n \"id\": \"https://dout.dev/posts/2026-06-30-rss-json-feed-sitemap-at-build-time.html\",\n \"url\": \"https://dout.dev/posts/2026-06-30-rss-json-feed-sitemap-at-build-time.html\",\n \"title\": \"RSS + JSON Feed + Sitemap at Build Time\",\n \"date_published\": \"2026-06-30T08:00:00Z\",\n \"summary\": \"The three distribution files every blog should ship...\",\n \"tags\": [\"seo\", \"static-site\", \"architecture\"]\n }\n ]\n}The cost of adding it is an extra file and twenty lines of generator code. The benefit is any reader that speaks JSON Feed gets richer metadata - tags, summaries, author - without the ceremony of extension namespaces in XML.
\nThe sitemap is for crawlers. If you ship it, ship everything. Partial sitemaps are worse than no sitemap because they implicitly tell the crawler \"these are the interesting pages,\" which de-weights everything not listed.
\nThe dout.dev sitemap includes posts, tag pages, month archives, series archives, the home page, the about page, and the search page. It does not include the 404, the offline page, or the playground.
\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">\n <url>\n <loc>https://dout.dev/</loc>\n <lastmod>2026-06-30</lastmod>\n <changefreq>weekly</changefreq>\n <priority>1.0</priority>\n </url>\n <url>\n <loc>https://dout.dev/posts/2026-06-30-rss-json-feed-sitemap-at-build-time.html</loc>\n <lastmod>2026-06-30</lastmod>\n </url>\n <!-- ... -->\n</urlset>The changefreq and priority fields are advisory. Google has said publicly that it mostly ignores them. I still ship them because other crawlers read them and the cost is nothing.
An underrated feature: each tag page and each month archive on dout.dev has its own RSS feed. A reader who cares about accessibility but not about css can subscribe to /tags/accessibility.xml and never see a post outside that tag.
The feeds are generated from the same dataset as the main feed, filtered to the tag or month. It is free to produce, because the normalized data already has the tag and month indexes.
\n<link rel=\"alternate\" type=\"application/rss+xml\" title=\"dout.dev - accessibility\" href=\"/tags/accessibility.xml\" />That <link rel=\"alternate\"> is how readers auto-discover the feed. Every tag page ships it.
None of this happens at runtime. The feeds and sitemap are generated when the CMS builds, committed as artifacts in dist/, and served as plain static files by GitHub Pages. That means:
Shipping RSS, JSON Feed, and a sitemap is an afternoon of generator code. The payoff is measurable: crawlers find your content, readers subscribe, and the blog stops being a black box to the rest of the web.
\nEvery image on this blog has to satisfy four non-negotiable constraints:
\nThe pipeline that delivers that is entirely build-time. There is no image CDN, no runtime resize, no magic. This post walks through each layer.
\nThe markdown source looks like a normal image:
\nWhat makes it responsive is not a special syntax. It is the build pipeline that sees the local path and does work behind the scenes.
\nOptionally the author can provide a title meta string to override the default behavior:
\n 100vw, 640px | priority=high | loading=eager')Segments separated by | let you specify custom srcset, sizes, loading, and priority. For most images I omit all of that and let the pipeline fill in the defaults.
Before the CMS runs, an image pipeline step generates responsive variants of every image under src/assets/images/:
image.jpg → image-320.jpg, image-640.jpg, image-960.jpg, image-1280.jpg, never upscaled;image.webp) and matching WebP variants at each size.The output of that step is a manifest file (src/assets/images-manifest.json) with entries like:
{\n \"/assets/images/keyboard.jpg\": {\n \"width\": 1920,\n \"height\": 1280,\n \"variants\": [\n { \"src\": \"/assets/images/keyboard-320.jpg\", \"width\": 320 },\n { \"src\": \"/assets/images/keyboard-640.jpg\", \"width\": 640 },\n { \"src\": \"/assets/images/keyboard-960.jpg\", \"width\": 960 },\n { \"src\": \"/assets/images/keyboard-1280.jpg\", \"width\": 1280 }\n ],\n \"webp\": [{ \"src\": \"/assets/images/keyboard-320.webp\", \"width\": 320 }]\n }\n}Sharp does the resizing. The manifest is the contract between the image step and the markdown renderer.
\n<img> into <picture>When the renderer encounters an image with a local path, it looks up the manifest, computes srcset for WebP and raster sources, and emits a <picture> element:
<picture>\n <source\n type=\"image/webp\"\n data-srcset=\"/assets/images/keyboard-320.webp 320w,\n /assets/images/keyboard-640.webp 640w,\n /assets/images/keyboard-960.webp 960w,\n /assets/images/keyboard-1280.webp 1280w\"\n sizes=\"(max-width: 640px) 100vw, 640px\"\n />\n <source\n type=\"image/jpeg\"\n data-srcset=\"/assets/images/keyboard-320.jpg 320w, ...\"\n sizes=\"(max-width: 640px) 100vw, 640px\"\n />\n <img\n src=\"/assets/images/keyboard.jpg\"\n alt=\"A keyboard on a wooden desk\"\n width=\"1920\"\n height=\"1280\"\n loading=\"lazy\"\n decoding=\"async\"\n />\n <noscript>\n <img src=\"/assets/images/keyboard-640.jpg\" alt=\"A keyboard on a wooden desk\" />\n </noscript>\n</picture>Two details worth calling out.
\nWidth and height come from the manifest. The browser reserves the correct aspect-ratio box before the pixels arrive, so there is no layout shift when the image loads. This is the single most impactful CLS fix on any image-heavy page.
\ndata-srcset instead of srcset by default. The real srcset is swapped in by a tiny script when the image enters the viewport, which is how the \"lazy on-reveal\" policy is enforced. The <noscript> fallback covers users who disable JavaScript.
For LCP-critical images (covers, above-the-fold hero), the author sets priority=high or loading=eager, and the renderer inlines real srcset attributes instead of data-srcset. No waiting, no flash.
data-srcset to srcsetThe runtime piece is small:
\nconst io = new IntersectionObserver(\n (entries) => {\n for (const entry of entries) {\n if (!entry.isIntersecting) continue;\n const source = entry.target;\n if (source.dataset.srcset) {\n source.srcset = source.dataset.srcset;\n source.removeAttribute('data-srcset');\n }\n io.unobserve(source);\n }\n },\n { rootMargin: '200px' }\n);\n\ndocument.querySelectorAll('source[data-srcset]').forEach((s) => io.observe(s));That is the entire lazy-load layer. Everything else is declarative markup the browser understands natively.
\nloading=\"lazy\" alone?Native loading=\"lazy\" is a good default and I use it on <img> elements. But it does not cover <source> elements inside <picture>. The IntersectionObserver swap handles the source selection path, which is where the large WebP variants are chosen.
On a page with a dozen images below the fold, the difference is measurable in bytes saved on initial load.
\nResponsive images do not need a service. A build step that generates variants, a manifest the renderer reads, and a markdown pass that emits <picture> are enough. The result is small pages, correct sizes, known dimensions, and lazy behavior that respects the user.
<picture> - MDNEvery time I started a personal site and went \"page first, design system later,\" I ended up with a pile of local exceptions. A margin-top: 24px here, a color: #f5a623 there, a breakpoint at 768px on one component and 720px on another. By the third page the design was already incoherent, and the only way to fix it was to go back and retrofit tokens onto a living codebase. That is the worst moment to do it.
For dout.dev I flipped the order. Tokens first, components second, pages third. This post is what that looks like in practice.
\nDesign tokens are not a library. They are a flat set of named decisions, expressed as CSS custom properties, about spacing, type, color, elevation, motion, and layout. The rest of the CSS reads those decisions and never hardcodes.
\nThe rule I hold to is simple: if a value appears in two components, it becomes a token. If it only appears once, I wait.
\n:root {\n /* Spacing scale */\n --space-1: 0.25rem;\n --space-2: 0.5rem;\n --space-3: 0.75rem;\n --space-4: 1rem;\n --space-5: 1.5rem;\n --space-6: 2rem;\n --space-8: 3rem;\n\n /* Type scale */\n --text-sm: 0.875rem;\n --text-base: 1rem;\n --text-lg: 1.125rem;\n --text-xl: 1.25rem;\n\n /* Line-height families */\n --font-lineheight-1: 1.1;\n --font-lineheight-3: 1.5;\n\n /* Surfaces and text */\n --surface-1: #0b0b0f;\n --surface-2: #161621;\n --text-primary: #e7e7ef;\n --text-muted: #a0a0b4;\n\n /* Focus */\n --focus-ring: 2px solid #ff6b3d;\n}That is a single source of truth. It does not know about pages. It does not know about components. It knows about decisions.
\nRaw tokens alone are not enough for a theme-able site. I use two layers:
\nPrimitive tokens - the raw decisions above. They never change at runtime.
\nSemantic tokens - aliases that map intent to primitives. These are the ones components actually read, and these are the ones that flip between themes.
\n:root {\n --color-bg: var(--surface-1);\n --color-bg-raised: var(--surface-2);\n --color-fg: var(--text-primary);\n --color-fg-muted: var(--text-muted);\n --color-accent: #ff6b3d;\n}\n\n[data-color-scheme='light'] {\n --color-bg: #fafafa;\n --color-bg-raised: #ffffff;\n --color-fg: #1a1a1a;\n --color-fg-muted: #555566;\n}Components then write color: var(--color-fg), never color: #e7e7ef. Theme switching becomes a matter of changing a handful of semantic tokens at the root, not rewriting every rule.
Three rules keep the CSS from rotting.
\nNo magic numbers in components. If a value is not a token, it is almost always a mistake. The exceptions are genuinely one-off values tied to a specific piece of geometry, and those get a comment.
\nNo color literals outside the token file. Not even in media queries, not even in box-shadow. If a color is referenced, it is via a variable.
No breakpoint literals outside a shared map. Breakpoints are tokens too, expressed as container query breakpoints or named media queries, never inline.
\n/* Good */\n.post-card {\n padding: var(--space-5);\n background: var(--color-bg-raised);\n color: var(--color-fg);\n border-radius: var(--radius-2);\n}\n\n/* Bad */\n.post-card {\n padding: 24px;\n background: #161621;\n color: #e7e7ef;\n border-radius: 8px;\n}The \"bad\" version works. It will also be unfixable in a year.
\nWhen I added the light theme and the accent selector, the change was a few dozen lines. Every component picked it up for free, because no component hardcoded a value. The dark mode toggle, the prefers-color-scheme hookup, and the accent switcher are all variations on the same idea: swap the semantic tokens at the root, let the cascade do the rest.
Without the two-layer setup, theming a site usually means touching every component. With it, theming is one file.
\nI did not build an elaborate token pipeline. No Style Dictionary, no JSON sources compiled into multiple formats, no cross-platform tokens. This is a single-target CSS project. A flat .css file that declares custom properties is enough, and any tooling beyond that would be overhead without a matching benefit.
If the project grew multiplatform - iOS, Android, email, a design tool plugin - I would pull in Style Dictionary. Until then, one file and discipline.
\nIf you are starting a personal site or a small design system, write the token layer before the first page. It costs an afternoon. It buys you theming, consistency, and the ability to make design changes in one place instead of twenty.
\nProgressive enhancement has had a rough decade. Between single-page apps, islands architecture, and \"modern web\" sermons, the idea that a page should work without JavaScript got treated as either trivial or reactionary. Neither is true.
\nThe version I hold to, and that dout.dev ships, is this:
\n\n\nEvery page renders, navigates, and communicates its core purpose without running a single byte of JavaScript. Every interactive feature is an enhancement, not a prerequisite.
\n
That is a contract. It is falsifiable. You can test it by disabling JavaScript in the browser and clicking around.
\nA reader with no JavaScript, either by choice or because the script failed to load, gets:
\nsearch.html page has a <form method=\"get\" action=\"/search.html\">. With JS it filters live; without JS it is submitted as a GET request and the page loads with the same URL shape.<head>.What the reader loses: live search filtering, theme switching, scrollspy highlighting, the lazy-load WebP swap (native loading=\"lazy\" on the fallback image still works), and the clipboard-copy button on code blocks.
Everything the reader loses is an enhancement. Nothing that is essential to reading the blog requires JavaScript.
\nThe contract is enforced at markup time. Every interactive feature is layered on top of a working HTML primitive.
\n<form role=\"search\" method=\"get\" action=\"/search.html\" data-search-form>\n <label for=\"q\">Search</label>\n <input type=\"text\" id=\"q\" name=\"q\" />\n <button type=\"submit\">Search</button>\n</form>With JS disabled, submitting the form loads /search.html?q=whatever. The server-rendered search page parses the URL and displays results from the prebuilt JSON indexes - no JS needed for that match, because the JSON is small enough to be parsed server-side at build.
Wait, a static blog has no server. Right. The \"server\" in this case is the CMS, which at build time generates /search.html as a shell that reads URL params on page load. Without JS, the form submits, the page reloads with the URL, and the page itself shows a placeholder: \"Enable JavaScript for live search, or browse by tag or month below.\" That placeholder links to the archive pages, which are fully static.
That is the graceful-degradation path for search. It is not as good as the JS path, but it does not dead-end the reader.
\n<button data-theme-toggle aria-pressed=\"false\" hidden>Toggle theme</button>The button is hidden in the initial markup. Only the JS that actually implements the theme switch removes the hidden attribute. Readers without JS never see a button that does nothing.
This is a general pattern: any UI element that requires JS to function is hidden by default and revealed by the enhancement script. The opposite pattern - show the button, have it do nothing when clicked - is worse, because it breaks the \"visible things work\" contract that users assume.
\nThe outline navigation is a normal list of jump-links. Without JS, clicking a link scrolls to the section. With JS, the active section gets highlighted as the user scrolls. The enhancement is purely decorative; the base experience is unchanged.
\nFenced code blocks render as plain <pre><code> in the markdown output, upgraded by <pre is=\"pix-highlighter\"> when JS runs. Without JS, the code is monospaced and unhighlighted. Readable. Not pretty.
The copy button is added by the custom element's connectedCallback - no element in the pre-JS DOM, nothing to fail.
Writing the contract is not enough. The build enforces it with a small no-JS check.
\nimport { test } from 'node:test';\nimport { chromium } from 'playwright';\n\ntest('home renders without JS', async () => {\n const browser = await chromium.launch();\n const context = await browser.newContext({ javaScriptEnabled: false });\n const page = await context.newPage();\n\n await page.goto('http://localhost:3000/');\n\n const main = await page.$('main');\n const text = await main.textContent();\n\n if (!text.includes('Welcome to dout.dev')) {\n throw new Error('Home content missing with JS disabled');\n }\n\n const posts = await page.$$('a[href^=\"/posts/\"]');\n if (posts.length < 5) {\n throw new Error('Post list not rendered without JS');\n }\n\n await browser.close();\n});The check runs against the home, the archive, a random post, and the search page. It asserts that the essential content is present, that internal links resolve, and that no error text is shown. If any of these fails, the quality gate stops the build.
\nThat is the difference between \"we care about progressive enhancement\" and \"the site provably works without JS.\"
\n:has(), you get a simpler layout; you still get the content. But I do not vendor polyfills for IE11.Progressive enhancement is a testable contract, not a stance. Pick a clear line - \"the core experience works without JS\" - and let the build verify it. The result is a more resilient site and a simpler mental model. The enhancements can then be as ambitious as you want, because you know what they are enhancing.
\n<noscript> - MDNA blog is a time-ordered list of posts. That linear view is useful for the home page and the RSS feed. It is bad for discovery. Readers who arrive on a single post want a way to find more like it, and \"more like it\" is not a single axis.
\ndout.dev ships three archives:
\n/tags/<slug>.html. Topical similarity. \"Show me all the accessibility posts.\"/months/<YYYY-MM>.html. Temporal browsing. \"What did you write in 2026-03?\"/series/<slug>.html. Intentional groupings. \"Read the making-of series in order.\"Each is a first-class surface with its own page, its own RSS feed, its own OG image, and its own pagination. All three are generated from the same normalized dataset the post generator uses, so there is no drift between what a tag page shows and what the post pages claim.
\nThe URL contract is opinionated and consistent across the three archives.
\n/tags/accessibility.html, /months/2026-08.html, /series/making-of.html./tags/accessibility/2/, /months/2026-08/2/, /series/making-of/2/.Why the split? Two reasons.
\nFlat URLs for page 1 are canonical. They are the URLs that show up in RSS feeds, sitemaps, and shares. They should look like leaves of a tree, not like indexes.
\nSubfolders for pages 2+ prevent URL-pattern collision. A URL like /tags/accessibility/2.html looks like it might be a post slug. /tags/accessibility/2/ is unambiguously a paginated archive.
The templates in the repo enforce this. The paginator receives the scope and the page number and emits the URL based on these rules, not string-concatenated from an input.
\nPagination on an archive is the same pagination on the search page, which is the same pagination I will ship on any future list view. It lives in one component, src/components/pagination.html, and gets included.
<include src=\"../components/pagination.html\"></include>The parent template exposes a pagination object with the shape:
{\n current: 1,\n total: 3,\n baseUrl: '/tags/accessibility/',\n items: [\n { kind: 'prev', url: null, disabled: true },\n { kind: 'number', page: 1, url: '/tags/accessibility.html', current: true },\n { kind: 'number', page: 2, url: '/tags/accessibility/2/', current: false },\n { kind: 'number', page: 3, url: '/tags/accessibility/3/', current: false },\n { kind: 'next', url: '/tags/accessibility/2/', disabled: false },\n ],\n}The component renders that shape. Every archive and the search use it. One source of truth for styling, for accessibility, for behavior.
\naria-current, rel=\"prev\" / rel=\"next\", and the ellipsis problemThree small details that make pagination accessible and crawlable.
\naria-current=\"page\" on the current page link. Screen readers announce \"current page, 2 of 5\" instead of just \"2.\" That is the correct value for pagination, as opposed to aria-current=\"location\" which is what I use for scrollspy anchors.
rel=\"prev\" and rel=\"next\" on the adjacent page links. Crawlers use these to understand that the pages are part of a paginated sequence. Google has officially deprecated rel=\"prev/next\" for Search, but other crawlers still respect it and the cost is nothing.
Ellipses are not links. When there are many pages, the pagination compresses with ... markers. Those markers are <span>, not <a>. A keyboard user who tabs through pagination should not land on a non-interactive element, and a screen reader should skip them.
<nav data-pagination aria-label=\"Pagination\">\n <a href=\"/tags/accessibility.html\" rel=\"prev\">Previous</a>\n <a href=\"/tags/accessibility.html\">1</a>\n <a href=\"/tags/accessibility/2/\" aria-current=\"page\">2</a>\n <span aria-hidden=\"true\">...</span>\n <a href=\"/tags/accessibility/5/\">5</a>\n <a href=\"/tags/accessibility/3/\" rel=\"next\">Next</a>\n</nav>The aria-label=\"Pagination\" on the <nav> is required because the page has more than one <nav> element (primary nav, post nav, archive pagination).
Each archive has its own RSS feed. /tags/accessibility.xml contains only posts tagged accessibility. Subscribers who care about one topic can follow it without seeing the rest.
<link rel=\"alternate\" type=\"application/rss+xml\" title=\"dout.dev - accessibility\" href=\"/tags/accessibility.xml\" />The feed is generated from the tag-filtered subset of the dataset. Same template, same pagination-less shape (RSS does not paginate), different inputs. About ten extra lines of generator code per archive type.
\nSlugging is the kind of thing that looks trivial until it bites. The rules:
\nfunction slugify(input) {\n return input\n .toLowerCase()\n .normalize('NFKD')\n .replace(/[\\u0300-\\u036f]/g, '') // strip diacritics\n .replace(/[^a-z0-9-]+/g, '-')\n .replace(/-+/g, '-')\n .replace(/^-|-$/g, '');\n}The slug normalizer runs on every tag at CMS normalization time. Tags that slugify to the same value are merged with a warning in the build output. That prevents the \"CSS\" / \"css\" / \"Css\" tag fragmentation that happens without a rule.
\nTags are unordered. Series are ordered. A series archive renders the posts in publication order, not reverse chronological, because the reader wants part 1 before part 2.
\nif (archive.kind === 'series') {\n posts.sort((a, b) => a.date.localeCompare(b.date));\n} else {\n posts.sort((a, b) => b.date.localeCompare(a.date));\n}That is a six-line difference in the generator. The templates do not need to know - they receive posts in the correct order and render them.
\nArchives are a design surface, not a free byproduct of having tags. Decide the URL shape. Ship a single pagination component. Respect the accessibility details that keep pagination usable with a keyboard and a screen reader. Give each archive its own feed. The result is a blog that is actually discoverable, not just readable.
\nrel=\"next\" and rel=\"prev\" - MDNaria-current - ARIA Authoring Practices GuideThree constraints that usually pull in different directions.
\nReadable like HTML. A template should look like a document, not a programming language wearing angle brackets. No curly-heavy logic mixed into markup.
\nExpressive enough for a real blog. Conditionals, loops, nested layouts, inline expressions - the minimum viable set has to cover these or the CMS ends up exporting special-case data structures for every page type.
\nNo eval. Anything user-controlled that turns into runtime code is a liability. The expression evaluator had to parse and interpret, not delegate to the JavaScript engine.
The resulting engine is a few hundred lines and lives under scripts/template-engine/. It runs during the CMS build. It does not ship to the browser.
The grammar has exactly four things.
\n<extends src=\"...\"> - a template declares that it extends a base layout. The base layout contains named slots.
<block name=\"...\"> - inside an extending template, a block overrides the same-named slot in the base layout.
<include src=\"...\"> - inline composition. The included fragment is inserted with access to the current context. Typical uses: the pagination component, the post card, the footer.
Expression references - an expression reference can use an optional filter pipeline. Filters are ordinary functions. The grammar for expressions supports member access, ternary, logical operators, and literal values.
\nControl flow is expressed with custom elements that look like HTML: <if condition=\"...\">, <for each=\"item in collection\">, <switch> with <case> and <default>. That keeps the templates in one grammar instead of mixing angle brackets with mustache-style blocks.
The engine parses the base layout once and indexes its blocks by name. When an extending template is rendered, the engine walks the child template, collects its <block> elements, and uses them to override the parent slots. Anything in the extending template outside of a block is discarded by design - it would have no stable place to land.
The practical upshot is that a post template reads like this:
\n<extends src=\"./layouts/base.html\">\n <block name=\"title\">Title from context - dout.dev</block>\n <block name=\"content\">\n <article>...</article>\n </block>\n</extends>The base layout declares the slots:
\n<title><block name=\"title\">dout.dev</block></title>\n<main><block name=\"content\"></block></main>Slots can have default content. Blocks are required only if the parent says so.
\nExpressions for values like post cover dimensions or tag counts look like JavaScript. They are not - they are parsed into a small AST and walked by an interpreter.
\nThe interpreter supports:
\n&&, ||, !;Everything else is a syntax error. No global lookup, no prototype walk, no Function constructor. The evaluator is stateless and only reads from the context object passed in.
This matters for two reasons. First, it means rendering a template is deterministic and side-effect-free. Second, it means I can treat the template language as a safe expression surface, even when the inputs are derived from user content.
\nA common alternative is to use curly-brace blocks for conditionals, loops, and closing statements. I tried that. The mix of angle brackets and curlies made templates hard to read for non-trivial layouts. Using custom elements like <if> and <for> keeps the document shape consistent. Editors and formatters treat them as HTML; the indentation logic is obvious.
There is one rule I learned the hard way: do not nest <if> inside an opening tag to conditionally add attributes. The parser gets confused, and so does the reader. Use inline expressions in the attribute value instead:
<img width=\"expression: cover width or empty\" height=\"expression: cover height or empty\" />That rule is documented in the repository README, because it is one of those things that tripped me up twice before I wrote it down.
\nIt does not support runtime templates from untrusted content. It does not re-parse the base layout per render; that is cached. It does not allow templates to import JavaScript. It does not have a plugin system.
\nIt does what a blog needs. The features I do not add are the features I do not have to maintain.
\nIf you are building a custom SSG and want templates that read like HTML, you do not need a full templating library. A few hundred lines of parser, a four-primitive grammar, a small set of filters, and a sandboxed expression interpreter covers the whole surface of a well-behaved blog. The features you do not add are the features you do not have to maintain.
\n", "image": "https://dout.dev/assets/og/posts/2026-05-13-template-engine-and-template-structure.png", "date_published": "2026-05-13T00:00:00.000Z", "tags": [ "Making-of", "Template-engine", "Html", "Architecture" ] }, { "id": "https://dout.dev/posts/2026-05-12-custom-ssg-pipeline.html", "url": "https://dout.dev/posts/2026-05-12-custom-ssg-pipeline.html", "title": "Custom SSG Pipeline: Markdown to Static HTML", "summary": "The pipeline, in one picture", "content_html": "Everything starts in data/posts/. Each post is a markdown file with YAML front matter. The build is four stages:
src/.The pipeline is a plain Node script orchestrated from scripts/cms/build.js. No framework, no plugin system, no watcher magic outside of a small cms:watch entry point.
The scan step reads the directory and returns an array of raw post records. It is the thinnest possible layer: one call to gray-matter per file, a sanity check on required fields, and a sort by date.
What the scan does not do is also important: no rendering, no side effects, no cross-post computation. If the scan fails, it fails loud, at one file, with a clear message. That makes debugging content errors a five-second loop.
\nNormalization is where most of the thinking happens. Given the raw post records, it produces:
\nThis step is deliberately pure. Given the same inputs it returns the same outputs. That lets the page generator be a dumb renderer and lets the tests be boring.
\nThe renderer walks the normalized dataset and writes files. For each post it renders the post page. For each tag, month, and series it renders the listing page and, if needed, subsequent paginated pages at /{scope}/{slug}/{n}/. It also renders the home, archive, about, playground, offline, and 404 pages.
The template engine is small and understands four things: extending a base layout, declaring blocks, including fragments, and evaluating expressions with filters. There is no virtual DOM, no hydration layer, no partial rendering. The output is HTML.
\nThe renderer is where the editorial shape of the site is visible. Every view is a template that describes a real document, not a component tree that happens to serialize to HTML. You can open the generated src/posts/*.html and read it like a normal document. That is the property I wanted.
The final stage produces everything that is derived but not a page:
\nfeed.rss, feed.json, feed.xml for subscribers;sitemap.xml for crawlers;src/data/*.json for the client-side search index;src/assets/og/posts/*.png for social previews.OG images are worth their own post; they are rendered server-side at build time from an SVG template and rasterized with Sharp. That one decision - \"generate them at build, never at runtime\" - eliminated an entire category of infrastructure I did not want to maintain.
\nThree constraints keep the code honest:
\nOne pass, no hidden passes. Every derivation lives in the normalize step. The renderer never computes global state. The emitter never reaches back into the renderer. The dataset flows in one direction.
\nNo dynamic content at runtime. Everything that can be precomputed is precomputed. The only thing running in the browser is the small progressive-enhancement layer: theme switching, search over the prebuilt indexes, scrollspy, and the Giscus comments.
\nNo framework to appease. There are no \"pages\" folders, no special file-based routing rules, no magic exports. Every page exists because a script wrote it.
\nThe result is a build that runs in under a few seconds on a cold cache and is cheap enough that I never think about it. The pipeline is small enough to read end-to-end in an afternoon.
\nThe next post in this series goes into how extends, block, include, and the expression grammar work without eval - and why the grammar is close to HTML instead of curly-brace syntax.
If someone asks me today \"what should I use for a personal developer blog,\" my answer is almost always Astro. It is a reasonable default. The ergonomics are good, the output is lean, the community is active, and the opinionated parts are mostly defensible.
\nFor dout.dev, I did not pick Astro. Nor Eleventy, nor Next. I wrote a static site generator from scratch, on purpose. This post is the honest accounting of why - not to argue the frameworks are wrong, but to explain when building your own pipeline is actually a reasonable choice rather than a vanity project.
\nFrameworks are not free. The invoice just arrives late.
\nUpgrade churn. A blog is a ten-year project, not a sprint. Every framework I have ever used for a side project demanded a non-trivial migration every two to three years. The migrations are rarely hard; they are consistently annoying. Multiply by the number of projects you maintain. Compare to plain markdown, HTML, and CSS, which have needed zero migrations for twenty years.
\nOpinion bleed. Frameworks encode opinions about routing, data fetching, layout composition, hydration, bundling. Most of those opinions are good. A few will collide with what you actually want, and the escape hatches are usually worse than the happy path. For a blog, I wanted opinions I already hold - about accessibility, about URL shapes, about progressive enhancement - not opinions a framework has about islands or RSC.
\nRuntime ballast. Even \"zero-JS-by-default\" frameworks ship a non-trivial runtime once you add interactivity. For a blog that is mostly text, every kilobyte of framework JavaScript is paying for a feature I am not using. Users on slow networks pay for it twice.
\nNone of these are deal-breakers. They are line items. For some projects the line items are fine. For this one, I wanted the invoice to be short.
\nI did not rebuild the world. I rebuilt a small, boring world where every component is easy to replace and every layer is under two hundred lines.
\nThe SSG is a markdown-to-HTML pipeline that emits posts, tag and month archives, series, paginated listings, RSS, JSON Feed, sitemap, and OG images. The template engine is a small one that reads templates extending a base layout and fills blocks. The CMS is a normalization step that reads front matter, derives slugs, builds indexes, and hands typed data to the page generator. The design system is a set of CSS custom properties and a few dozen components.
\nThe total amount of code I maintain is small enough that I could rewrite the whole pipeline over a weekend if I needed to. That is the ceiling I wanted.
\nNo ecosystem. No plugins, no content collections, no MDX components written by someone smarter. Whatever I need, I write. That is fine for a blog; it would not be fine for a product.
\nNo free lunches. The responsive image pipeline is mine. The OG image renderer is mine. The search index is mine. The pagination URLs, the rel=\"next\" tags, the structured data - all of it mine. That is where the AI copilot paid for itself, because writing those from scratch without help would have been the kind of slog that kills side projects.
No upgrade path. When a web platform API becomes interesting, I integrate it myself. When a framework adds a feature I envy, I reimplement the interesting part.
\nThis post is not \"frameworks are bad.\" They are often the right choice. I would reach for Astro or Eleventy when:
\nNone of those applied here. dout.dev is a personal editorial project with a single author who has opinions and time.
\nPick the tool that matches the ten-year horizon of the thing you are building, not the ninety-minute horizon of the first post. For most people that points at Astro. For this project - single author, strong opinions, no migration budget - it pointed at a handful of scripts and a design system I own end-to-end.
\nIf you are starting a blog today and you want to ship something this weekend, use Astro. If you want to understand every line that runs, build the pipeline yourself. Both are defensible. The mistake is building the pipeline when you wanted to ship, or picking a framework when you wanted to understand.
\n", "image": "https://dout.dev/assets/og/posts/2026-05-05-why-no-astro-eleventy-next.png", "date_published": "2026-05-05T00:00:00.000Z", "tags": [ "Making-of", "Architecture", "Static-site" ] }, { "id": "https://dout.dev/posts/2026-04-28-rebuilding-dout-dev-with-ai-copilot.html", "url": "https://dout.dev/posts/2026-04-28-rebuilding-dout-dev-with-ai-copilot.html", "title": "Rebuilding dout.dev in Weeks With an AI Copilot", "summary": "The honest framing", "content_html": "I did not \"ask an AI to build my blog.\" I rebuilt dout.dev as a hands-on engineering project and used an AI copilot the same way you would use a very patient, very fast pair-programmer who happens to remember every file you pointed at. The difference from previous attempts is not that I wrote less code. It is that I spent far less time on the parts that used to drain me: boilerplate, repetitive refactors, sanity-checking conventions across hundreds of files, and the kind of careful mechanical work that makes a codebase consistent.
\nWhat used to be a three-month weekend project compressed into a handful of focused sessions, split across nineteen milestones. This is the tally.
\nThe roadmap is not a vague \"rewrite\" entry. It is a sequence of concrete units of work:
\nEach milestone had an exit checklist. When the list was green, I moved on. That discipline is what kept the AI useful instead of making it a distraction.
\nThree things carried most of the weight.
\nRepeat-at-scale edits. Rename a token across the design system, adjust heading semantics in dozens of templates, regenerate feed entries when the schema changes. I described the intent once and audited the diff afterwards. That is maybe a third of the total time I spent on the rewrite, and it is the part I would otherwise have abandoned.
\nSearch-and-explain inside the repo. \"Show me every place where we compute the canonical URL.\" \"What renders the article sidebar and where does the scrollspy wire up?\" I would have answered these questions eventually with ripgrep and memory. The copilot answered them in seconds and kept me in flow.
\nDrafts I could edit. For the template engine, the CMS normalization, the OG image renderer, the archive paginator, I asked for a starting draft, read it, threw away the parts I did not like, and shaped the rest. That is faster than a blank file, and it is faster than copying-and-adapting something I half remember from a past project.
\nThe architecture decisions. Whether to use a framework or build a template engine. Whether to render OG images with Sharp at build time or punt to a runtime service. Whether to accept an extra dependency for code highlighting or write a custom element. What \"WCAG 2.2 AA\" actually means in the post layout and how to verify it. The CSP. The information architecture of archives. The pagination URL shape.
\nI also did not delegate judgment on code quality. The copilot would happily write something that works; I read the diff and asked for a smaller, simpler, more boring version at least half the time. Boring is a feature.
\nIt invented a nonexistent flag in a tool once. It occasionally produced patterns that passed tests but did not match the rest of the codebase. It sometimes wrote comments that described the task instead of the code. And it needed to be told, often, that adding error handling for an impossible case is worse than not adding it.
\nNone of these are catastrophic. All of them are the reason a human still reads every diff.
\nRealistic estimate, without the copilot, for the nineteen milestones in the shape they landed: three to five months of evenings and weekends. With the copilot, driven hard with clear prompts and strict reviews: a handful of focused weeks. The ratio is not 10x and it is not 2x. It depends on the task. Mechanical refactors and exploratory scaffolding are much faster; architectural decisions and accessibility audits are not.
\nThe more honest measure is that I finished. The previous rewrites stalled around milestone M5 or M6, because the gap between \"I can see the finish line\" and \"I have the energy to walk there\" was too wide.
\nWriting posts is no longer a project. The pipeline turns markdown into a pre-rendered, accessible, fast page with feeds, sitemap, OG image, and comments - in the time it takes to run one build command. That is what nineteen milestones of engineering bought.
\nThe rest of this series walks through each layer: what it does, why it is shaped that way, and where the tradeoffs landed.
\n", "image": "https://dout.dev/assets/og/posts/2026-04-28-rebuilding-dout-dev-with-ai-copilot.png", "date_published": "2026-04-28T00:00:00.000Z", "tags": [ "Making-of", "Ai-copilot", "Workflow" ] }, { "id": "https://dout.dev/posts/2026-04-21-cms-and-markdown-processing.html", "url": "https://dout.dev/posts/2026-04-21-cms-and-markdown-processing.html", "title": "CMS and Markdown Processing", "summary": "The useful distinction", "content_html": "A recent OpenReplay piece, The Good And Bad Of Using Markdown As A CMS, makes a distinction that matters more than it first sounds. \"Markdown as a CMS\" can mean at least three different systems:
\n.md files in a repository;Those are related, but they are not the same thing. The trade-offs move with each one.
\nOn dout.dev, the setup is plain Markdown plus front matter, a custom CMS pipeline, and an HTML-native template engine. No MDX. No admin UI. No database. That choice is excellent for some problems and the wrong answer for others.
\nFor developer-owned content, Markdown remains hard to beat.
\nThe obvious reason is version control. A post is a text file in Git. Diffs are readable. Rollback is trivial. Branches and pull requests already are the review workflow. If the site generator changes in five years, the content survives because the content format is not proprietary.
\nThe less obvious reason is maintenance. Raw HTML content ages badly. Inline styles accumulate. Broken nesting sneaks in. One-off classes appear for formatting hacks. Markdown constrains the authoring surface on purpose, and that constraint is usually a feature.
\nFor a blog, documentation site, changelog, or engineering handbook, this is a strong fit. The people writing are usually the same people maintaining the build, and the content itself is mostly narrative rather than highly relational data.
\nThe OpenReplay article is right about the breaking points.
\nPlain files do not give you content relationships for free. \"Posts by author\", \"localized variants\", \"schedule this for next Tuesday\", \"send it through approval\", \"let marketing edit it without Git\" - none of that is inherent in Markdown. At that point Markdown is a storage format, not the whole publishing system.
\nThis is also where a lot of Markdown debates get sloppy. People say \"Markdown cannot do X\" when what they really mean is \"a directory full of .md files without surrounding tooling cannot do X.\" That is true. It is also incomplete, because a project can add a lot of structure around Markdown before it reaches for a headless CMS.
dout.dev is not \"just Markdown files in a repo.\"
\nThe CMS layer reads front matter, normalizes content, derives slugs, builds tags, month archives, and series datasets, and generates pages from those derived records. The renderer also builds feeds, search data, and OG images. The image pipeline turns a normal Markdown image into a responsive <picture> with WebP sources, known dimensions, lazy loading, and a <noscript> fallback. Pull requests also get a built preview artifact, which is enough for review even though the site stays fully static.
That changes the shape of the problem. For this project, Markdown is the authoring format but the CMS is the surrounding pipeline: content normalization, derived relationships, image processing, deterministic HTML output, validation and CI before publish. Structured taxonomies exist. Media handling exists. Preview exists. Parser behavior is consistent because there is one Markdown pipeline.
\nThe system is better than plain files alone, but it is still intentionally narrow.
\nIt is not a good fit for non-technical editors. There is no admin UI. The workflow is still Git-first.
\nIt is not a good fit for approval-heavy editorial teams. There are drafts through published: false, local watch mode, and CI preview artifacts, but there is no role model, no approval chain, and no true scheduled publishing workflow today.
It is not a good fit for localization-heavy content. The site is English-only, and that is a product decision as much as a technical one.
\nIt is not a good fit for dynamic or highly relational domains. Comments can be outsourced to Giscus, search can be client-side, and analytics can be added carefully. But if the core content is products, inventory, user-generated data, or frequently mutating records, a database-backed CMS or API is the correct tool.
\nThis is the part worth being honest about: dout.dev bypasses some Markdown problems by adding custom infrastructure, but it does not magically turn Markdown into a universal CMS.
\nUse Markdown when the content is text-first, developer-owned, and benefits from living next to the code. Use a headless CMS when the content is structured, multi-author, localized, workflow-heavy, or owned by people who should never have to think about Git.
\nFor dout.dev, Markdown is the right source format: single author, strong opinions about portability and static output, content that is mostly narrative. For a marketing team, product catalog, or newsroom, I would not stretch this model.
\nMarkdown is a great source format. It is sometimes a CMS. It is never all of the CMS by itself.
\n