Building a docs site that scores 100 on Lighthouse
1 min readWeb developmentPerformance
A documentation site is mostly text, which is the easiest thing on the web to make fast. Yet many docs portals ship megabytes of JavaScript to render headings.
Render on the server#
Parse Markdown at build time and ship HTML. The reader's browser never downloads the parser.
import { parseMarkdown } from "@/lib/markdown";
export function Article({ source }: { source: string }) {
const blocks = parseMarkdown(source);
return <Markdown blocks={blocks} />;
}Hydrate only what's interactive#
Search, the theme toggle and copy buttons need JavaScript. Everything else doesn't. Keep those islands small and let the rest be static.
Fonts and images#
- Self-host fonts with
font-display: swapand subset them - Always set image width and height to prevent layout shift
- Use modern formats and lazy-load below the fold
Accessibility checklist#
| Item | Why |
|---|---|
| Visible focus ring | Keyboard users need to see where they are |
| Semantic headings | Screen readers navigate by heading |
| Sufficient contrast | Text must be readable in every theme |
| Reduced motion | Animations shouldn't force motion on anyone |
Guard it in CI#
A one-time 100 means nothing if it regresses next sprint. Run Lighthouse CI on every pull request and fail the build when a score drops below your budget.
Want this applied to your docs?
We'll audit what you have and tell you where the biggest wins are.
Talk to the team