Our own website, finally live

Fast to load, easy to publish

We started with two aims. The site had to be fast, with a target of 100 in all four LighthouseGlossary · In briefLighthouseLighthouse is an open-source tool from Google that automatically audits web pages for performance, accessibility, best practices, SEO and more.Read more⁠ categories. This Google tool checks websites for performance, accessibility, best practices and SEO. We also wanted menus, filters, carousels and forms that make the site pleasant to use. Speed had to come from how we built the whole thing.

We also wanted to leave the CMSGlossary · In briefCMSA CMS is software that lets users create, organize, edit and publish digital content, usually through an administration interface.Read more⁠ behind. We used Contentful and wanted to arrange each page freely. Some text next to a photo, a row of cards, a quote somewhere along the way; each page needed its own order. Contentful can model all of that perfectly well. But filling in those blocks took so much work that it was putting us off publishing new content.

As a software agency, we spend much of our day in a text editor. We wanted to write our stories there too, with the freedom to move blocks around or insert a new one. Copy, paste, edit. That led us to the idea of storing pages as MarkdownGlossary · In briefMarkdownMarkdown is a way to add structure to plain text using simple characters, for example for headings, lists, emphasis, and links.Read more⁠ and letting the website handle their appearance.

Why we like working in text

The benefits of text files become clear when you want to change something. We can search every page, replace a term throughout the site or compare two versions. GitGlossary · In briefversion controlVersion control records changes to code, including who changed what and when. It lets developers collaborate, compare changes and return to an earlier version.Read more⁠ shows exactly which sentences changed. A colleague can comment before the change goes live, and we can bring an earlier version back. All from the editor we already use.

The same files are useful to scripts and AI agents. An agent can read existing pages alongside our writing guidelines and components. It doesn't need to operate a CMS or guess which input field belongs to which part of a page. The result is still a change to a readable file that we can review.

This fits into something we're doing more broadly at 10KB: company as code. Our website lives in 42KB, the repository where we also keep company knowledge, handbooks, working practices and infrastructure. We use version control and automated checks for things you might otherwise expect to find in a separate documents folder. That makes knowledge easier to find and use on the next job. We'll share more about 42KB and company as code in upcoming blog posts.

From instructions to a page

Below, you can compare an abridged MDX file with our complete Dutch services page. Point to a section to see which lines belong to it, or start with the source and find the result. Press Tab to move to the next block or Shift+Tab to go back. The focused block is highlighted immediately. Escape clears the highlight; on a touchscreen, tap a block.

The plugins read Markdown as a syntax tree: they know which bit is a heading, which is a paragraph and where an image sits. That lets them collect the heading and text below a side-by-side instruction and pass them to the right component. The author writes the content and chooses the pattern. The plugin translates it into the website.

At the top of the file, between the dashes, is the frontmatterGlossary · In brieffrontmatterFrontmatter is a block of metadata at the beginning of a content file, usually read by the tool that processes the file.Read more⁠: the title, description and main image, for example. We've taken some work out of this part too. Our frontmatter plugins connect language versions, generate breadcrumbs and SEO data, calculate reading time and find related articles. They can look at other pages to do this. A central list of cases feeds the case carousels, so we don't have to enter the same card in several places. The plugins also run in a defined order: first establish the language and tags, then look for related articles.

Resuming a page without hydration

Many frameworks deliver HTML first, then run the component code again in the browser to make the page interactive. Among other things, they restore which button belongs to which function and the application's current state. This is called hydrationGlossary · In briefhydrationHydration is the process of connecting server-rendered HTML with client-side code and application state to make a page interactive.Read more⁠. The page may already be visible while the browser is still getting it ready to use.

Qwik stores that information with the HTML. A button effectively carries the address of the code it needs. The framework doesn't have to revisit every component when someone arrives. This approach is called resumability. Think of loading a saved game: you pick up where you left off, with the necessary state already recorded.

There is still JavaScript. The menu needs to open and the form needs to respond. What changes is when the code is needed. We can split it up and load it selectively, so a visitor doesn't have to download the workings of the entire page before reading the first paragraph.

One photo becomes several files

We do much of the image work during the build, when the source files are turned into the website we're going to publish. A large photo is resized and compressed into several variants. We do that calculation when we publish; visitors receive files that are already waiting for them.

The right variant depends on both the space the image occupies and the screen showing it. A phone usually needs fewer pixels than a large monitor, though a sharp phone display can have a higher pixel density. Our image pipeline therefore works with the actual widths of components and creates variants for different screen sizes and pixel densities.

With srcset, we give the browser a list of those files to choose from. With sizes, we tell it how much room the image will take up in the layout. That second detail mattered: if the browser thinks an image will be wider than it really is, it still picks an oversized file. We refined the widths specified for mobile heroes and added a smaller 384-pixel variant. The main image also has its own mobile crop.

Load the first screen first

Even a small file can arrive too late. The large image at the top needs to appear quickly; a photo at the bottom can wait. We give the first screen priority. A preload announces the hero image early, so the browser can start fetching it before it reaches the image itself. That announcement uses the same image variants as the hero. Otherwise, a phone could accidentally download two files.

Images further down use lazy loading: the browser fetches them as they approach the visible area. Their dimensions are already in the HTML, so it can reserve space. That keeps text from jumping down the page as images arrive.

We also worked on the styling. CSS defines how the page looks. The part needed for the first view comes with the HTML; the remaining styles can follow later. Vanilla Extract generates CSS during the build, and we serve fonts as compact local WOFF2 files. With font-display: optional, the browser can stick with an available font on a slow connection. It doesn't have to shift the text later to fit our font.

Fewer downloads aren't always faster

Optimisation brought a few surprises. Our general page route initially imported all MDX pages at once. That was convenient to begin with, but a visitor was coming for one page. We separated the server's metadata from the loaders for page content. We also import icons explicitly now, so one small icon doesn't accidentally pull in a whole collection of code. And we separated helpers used to build stylesheets from the code that goes to the browser.

We initially took a wrong turn with Qwik's preloader. It fetches code that may be needed shortly. Turning it off saved downloads on arrival, but when visitors clicked through, the browser had to fetch files one after another. Navigation felt slower. The preloader is now back on, and we've improved how the JavaScript bundles are grouped.

That's why we look beyond the first load. The next click, opening a menu and filling in a form all matter to how fast a website feels.

What the measurement shows

The Lighthouse report shows 98 for performance and 100 for accessibility, best practices and SEO. This test simulates a slow phone with a slow internet connection. In that run, the first content appears after 1.5 seconds, and the largest visible element after 2.4 seconds. Total blocking time is 60 milliseconds, with a layout shift score of 0. Content appears while the rest loads, with very little blocking work and no layout shifts in this measurement.

Those last two details matter as much as a high score. A page that looks loaded but doesn't respond to a tap still feels slow. And nobody enjoys a button moving just as they're about to press it. We also check for ourselves that the menu responds immediately and the next page opens quickly.

Back to writing

It took us a while, but the way we maintain the site now suits us. Text, components and publishing are part of the same workflow. An improvement to a component benefits several pages, and for each new story we can put the blocks in the order it needs. That's exactly what we used to struggle with in Contentful.

Our own website will probably never be completely finished. There's always another detail to improve or a download to make smaller. But the next time we have something to say, the technology will get in our way a lot less.