HAL: Build-Time Link Rewriting That Makes Navigation Feel Instant
Users judge a site in the first click. If navigating between pages feels sluggish, bounce rates climb and perceived quality drops - regardless of how good the content actually is. HTMX Auto-Linking (HAL) is the pattern I use to solve that problem at build time, with zero runtime cost.
The business problem
Every content site faces the same tradeoff: static HTML is cheap to host and great for SEO, but full-page navigations feel slow compared to a single-page app. The obvious fix - adding a client-side router - introduces a framework runtime, a bundle budget, and ongoing maintenance complexity. For a small team shipping a content product, that's a bad trade.
HAL sidesteps it entirely. During the build, it rewrites internal Markdown links into HTMX fragment swaps:
hx-get="/path/fragment.html"hx-push-url="/path"hx-target="#main-content"hx-swap="innerHTML"
Authors write normal Markdown. The build handles the rest. External links stay untouched, and you can opt out of any individual link with data-no-htmx or class no-htmx.
Why not a SPA router?
It comes down to cost, not ideology.
| Concern | SPA Router | HAL |
|---|---|---|
| JS payload | 20-40KB+ gzipped (router alone), often 100-300KB with framework runtime | 0KB additional - HTMX (~14KB) is already in the stack |
| Build complexity | Code-splitting, hydration, route config | One build-time string transform |
| Failure mode | White screen if JS fails | Full HTML page loads normally |
| Team onboarding | Learn the framework's routing conventions | Write Markdown links |
| Hosting cost | Often needs SSR or edge functions | Static files on any CDN |
For a team of one or two shipping a content-driven product, the SPA router column is a list of costs with no corresponding revenue. HAL gives you the UX benefit - instant-feeling navigation - without the engineering overhead.
How it fits the architecture
HAL is one layer in a stack designed to stay small and cheap. The static site generation playbook covers the full build pipeline, and the architecture overview explains how Web Components and HTMX fragments work together. If you're curious about measured performance gains, the HAL performance case study has real numbers.
Example links
- Traditional (opt-out): Case study without HAL (full page load)
- HAL-rewritten: Case study with HAL
When to opt out
Not every link should be a fragment swap:
- Download links or file refs that shouldn't replace the main content area
- Anchor links inside interactive widgets where swapping
#main-contentwould break context - Demo pages where you specifically need to show traditional navigation behavior
The takeaway
HAL is a build-time trick, not a runtime dependency. It makes navigation feel fast for the reader, costs nothing to maintain, and keeps the hosting bill at near-zero static rates. That's the kind of engineering decision that compounds - you get the UX win today and you don't pay for it tomorrow.