--- title: Building for reading date: 2026-06-12 published: 2026-06-12 tags: ['web', 'technology'] references: - /posts/replacing-hugo-with-go/ - /posts/optimising-the-build/ - /posts/reading-the-pagespeed-report/ description: "A plain site serves human readers well, while making content accessible to screen readers, text browsers, feed readers, and AI agents with minimal overhead." --- The posts here split roughly into two kinds: personal observations and thoughts, and reference-like material for documenting steps and recording notes. This site serves both audiences using a streamlined approach. ## The plain site The design is minimal by preference, involving no framework, no bundler, and a custom static site generator that produces clean HTML. CSS variables handle theming. JavaScript handles a few optional conveniences. I want content to be accessible without this overhead. A screen reader navigating the page encounters semantic HTML: `article`, `nav`, `footer`, `time` elements that carry meaning rather than just structure. A skip link at the top of every page jumps directly to the main content. The search dialog uses ARIA roles for the dialog, live region, and expanded state. SVG icons carry `aria-hidden` so they do not clutter the accessibility tree. Text browsers get a usable experience without any special handling. A page in Lynx or w3m is headings, paragraphs, links, and code blocks. There is no layout fighting with the text flow. Reading mode in Safari and Firefox strips the same page to text and renders it cleanly. Print mode gets its own attention: navigation chrome disappears, and printed links render with their URLs inline so a printed page stays useful without a screen. The vim-style keyboard navigation sits in this space too. `j` and `k` scroll, `gg` goes to the top, `G` to the bottom, `/` opens search, `[` and `]` move through paginated lists. These are mostly added as an easter egg. They work alongside standard browser shortcuts rather than replacing them. ## Machine access Several things on the site are aimed at non-human readers specifically. `/llms.txt` follows the emerging convention for AI agents: a structured index with titles, descriptions, and links. Each entry includes a link to the raw markdown source alongside the rendered HTML URL. The idea is that an agent wanting to read a post fetches the markdown directly rather than parsing HTML. Individual post sources are served as static files at predictable paths under `/content/`. The HTML page for each post also declares its raw source with a `` in the head, so a crawler that knows to look can find the clean version without consulting the index. `/atom.xml` is a standard Atom feed for readers and anything subscribing to new content. `/sitemap.xml` covers all pages. `/robots.txt` allows everything. JSON-LD structured data is embedded in the head of each page: article schema for posts with title, date, and description, along with Open Graph and Twitter card tags. ## Working together The reference posts benefit most from machine-readability. If someone asks an AI assistant about configuring LoRa channel registers, a useful answer requires clean extractable text, not an HTML page where the relevant three lines sit inside layout structure. Serving that text efficiently is worth the small effort. What the site does not do is treat these audiences as separate concerns requiring separate implementations. A page that is structurally simple, semantically marked up, and text-first serves all of them reasonably well at once. The things that help screen readers also help text browsers, which in turn makes content accessible for agentic workflows.