Everything KoIma ships with.

A tour of the theme — and, behind each feature, exactly how to configure it. This page lives in your copy of the theme, so the docs are always where your code is.

Essence ⇄ Everything — telescopic prose

In Essence, every page reads as its shortest honest self, with small […] chips wherever prose is held back — click one to unfold just that passage. The header toggle unfolds the whole page top to bottom, one passage at a time, each arriving with a fading moss highlight; folding back runs bottom to top, flashing what leaves. It works mid-sentence, on whole paragraphs, and inside headings.

You're reading a demo of it now, and this very sentence is one of the woven passages — in Essence mode it folds down to a small […] chip you can open on its own. Try the chip, then the toggle above.

Setup & config

Wrap any optional words, sentences or clauses in<ko-more> — directly inside your markdown (or any template). The surrounding text must read complete without it:

src/content/pages/intro.md

I'm Jon — a designer who makes small tools<ko-more>, mostly for stubborn personal itches,</ko-more> and keeps an honest [now page](/now).

For whole paragraphs, add the block attribute and blank lines so markdown keeps parsing inside:

block form

<ko-more block> A full markdown paragraph that only exists in Everything. </ko-more>

Headings telescope too — wrap the optional tail of a title:## Where it stands<ko-more> (sixty patient people later)</ko-more>. Everything is in the HTML (search engines always read the full text); CSS folds it viahtml[data-detail], the visitor's choice persists, and the […] chips are keyboard-accessible buttons. Reduced-motion visitors get instant swaps — no stagger, no highlight. The frontmatteressence line is used for list pages and meta descriptions.

Fast — measured, not promised

Every KoIma release is audited with Lighthouse before it ships. These are the real numbers from v1.0.0; they ship with the theme so you can re-run them yourself.

Mobile

100

Performance

100

Accessibility

100

Best practices

100

SEO

Desktop

100

Performance

100

Accessibility

100

Best practices

100

SEO

mobile: FCP 1.2 s · LCP 1.5 s · TBT 0 ms · CLS 0 — Lighthouse 13.4.0, median of 3 runs, 2026-06-11

Setup & config

Static HTML, fonts with font-display: optional, one small JS file, and the media modules fetched at build time — nothing on the critical path. Verify it yourself:

terminal

npm run build && npm run preview npx lighthouse http://localhost:4321 --view

Listening & Reading — your media, on your homepage

The last song you played (Last.fm) and the book you're reading (Goodreads) as quiet cards. Fetched at build time so nothing can break; the song refreshes live in the browser when configured.

Setup & config

src/data/modules.config.ts

lastfm: { user: 'your-username', liveRefresh: true }, goodreads: { userId: '12345678', shelf: 'currently-reading' }

Last.fm needs a free API key (last.fm/api) in .envas LASTFM_API_KEY — it's read-only, safe in the browser. Goodreads needs only the number from your profile URL; its RSS feed does the rest. Either module set to false removes its card; unconfigured modules show this sample data so the design never looks broken. If you've moved off Goodreads, Hardcover's API is the modern alternative — the card markup is yours to repoint.

A /now page with a memory

What you're doing now, in your own words — plus the archive of every past entry, because reading who you were two years ago is the real feature.

Setup & config

src/content/now/2026-06.md

--- date: 2026-06-01 essence: One line for the archive and Essence mode. --- The full entry — revealed in Everything mode.

One file per update; the newest is "now", the rest become the archive automatically. Three or four honest entries a year is the right cadence.

Lab — experiments with a status

Side projects as first-class citizens: ongoing, shipped, or honorably archived. Each entry has its essence and its whole story.

Setup & config

src/content/lab/your-tool.md

--- title: Your Tool essence: One sentence that earns the click. year: 2026 status: ongoing   # ongoing | shipped | archived featured: true    # show on the home page links: - label: Source url: https://github.com/you/tool ---

Notes — writing without ceremony

Markdown files become /notes/your-slug, listed newest-first. draft: true keeps one private.

Setup & config

src/content/notes/example.md

--- title: In defense of small software description: Forty-one users can be a complete success. date: 2026-04-12 ---

Instrument Serif & Sans — with a Typekit upgrade path

The demo pairs Instrument Serif (the voice — headings, the toggle, true italics) with Instrument Sans (the workhorse). One config change swaps in an Adobe Fonts pairing.

Setup & config

The recommended Adobe upgrade is the Freight superfamily:

theme.config.ts — Adobe Fonts

heading: { provider: 'adobe', family: 'freight-text-pro' }, body:    { provider: 'adobe', family: 'freight-sans-pro' } // + ADOBE_FONTS_KIT_ID in .env (fonts.adobe.com → Web Projects)

Also excellent on Adobe Fonts: Mrs Eaves + Mr Eaves (literary, airy) and Calluna + Calluna Sans (warm oldstyle). Google fallback ships working out of the box.

Every setting in one file

Colors, fonts, name, meta tags, social links and navigation live in theme.config.ts — typed, validated, and impossible to typo silently.

Setup & config

theme.config.ts

logo: { type: 'text', value: 'Your Name' }, colors: { accent1: '#2f6147', /* moss */ }

Invalid values fail the build with a readable error pointing at the exact field.

Light, dark and system color schemes are built in: the grey ramp inverts automatically in dark mode, colors.dark overrides any accent, and the toggle in the nav cycles auto → light → dark (persisted, no flash on load).

SEO without a plugin

Canonical URLs, Open Graph and Twitter cards, sitemap, robots.txt — fed by your config and per-page frontmatter.

Setup & config

any page

<PageLayout title="Page title" description="…" ogImage="/og-custom.png">

Demo content — keep it or strip it

The theme arrives as Jon Ko's site so every page has something to show. One command makes it yours.

Setup & config

terminal

npm run fresh

Removes the demo now/lab/notes entries and placeholder bio/contacts; resets the media modules to unconfigured. Structure and styles stay — the site builds immediately after.

Updates that respect your changes

Theme updates arrive as git pulls. Your config, content, styles, modules and overrides live in safe zones updates never touch.

Setup & config

update-safe

theme.config.ts src/data/modules.config.ts src/styles/custom.css src/content/ src/components/overrides/ public/

Don't edit src/_core/ — copy a component intosrc/components/overrides/ and change its import instead. Updating:

terminal

git fetch upstream && git merge upstream/main && npm install