Design

15 min read

Abstract

Shomosite is implemented as a Quartz site compiled from Markdown notes. The authored source lives in docs/, prose/, and product/; a staging script rewrites those source-shaped trees into the cleaner routes Quartz renders.

It is meant to be a serious personal hypertext: more like a small encyclopedia with arguments, product theses, sidenotes, previews, backlinks, and source-shaped structure than like a portfolio or a blog archive.

The design principles are: text first; minimalism with real affordances; semantic zoom; source-shaped authoring with reader-shaped routes; progressive enhancement; honest absence; and warm typographic restraint.

What does it take to make a personal site that can hold long-form arguments, working product ideas, and evolving system notes without turning into either a marketing page or a private vault accidentally exposed on the web?

That is the governing question. Shomosite borrows heavily from Gwern.net. The important lesson is that a writing system can be self-documenting, fast, dense, typographic, link-rich, and still approachable for the general reader. A site can let the reader skim at a distance, inspect the margin, open a preview, chase a backlink, and then return to the argument without feeling switched out of the original context.

Shomosite’s design therefore begins with architecture. The visible pages are only the final surface of a pipeline of eveolving Markdowns, active metadata, a staging boundary, Quartz parsing, custom render components, and automation scripts.

The characteristic harmony of restrain and featurefulness of this site comes from my goal to preserve the user’s attention as they read my content. The site is feature-rich but every feature earns its place by serving the user.

Benefit

The benefit of design work compounds across the site.

One essay can be written well and still sit inside a bad reading surface. One product note can be clear and still become hard to find, hard to cite, or hard to compare with neighboring ideas. A good shell cannot rescue bad writing, but a bad shell can tax good writing on every page. Since Shomosite is meant to accumulate prose and product reasoning over time, small design decisions matter more here than they would on a one-page announcement.

The site is not trying to impress the reader before the reader has read anything. It is trying to keep the argument inspectable after the first paragraph. That means the design has to do several jobs at once:

  • keep the main text calm and readable;
  • make structure visible without turning navigation into the subject;
  • let the reader open context in place instead of bouncing between pages;
  • keep private or unfinished references from becoming dead promises;
  • preserve the difference between authored source structure and rendered route structure;
  • make the system easy enough for an agent or future maintainer to reason about.

In that sense, the design is not an ornamental layer over the architecture. It is the architecture showing its manners.

Principles

There are seven design principles.

  1. Text is the primary interface.

The site is for reading first. Everything else is subordinate: the navigation, the margins, the preview windows, the homepage panels, the tags, the dates, and the search box. The typography has to be good enough that the default action is simply to read.

This is why the page uses a real article column rather than a full-width content wash. It is why the homepage opening keeps the same approximate reading measure as an essay. It is why note pages reserve a left rail for the table of contents and a right rail for margin notes instead of making the article fight for horizontal space with generic sidebars.

  1. Minimalism is not the same thing as feature poverty.

Shomosite should look quiet, but it should not be simple-minded. A serious hypertext needs previews, backlinks, search, section maps, note metadata, dark mode, and a navigable source structure. The design problem is not to remove those things. The design problem is to make them feel inevitable.

  1. Semantic zoom is the core reading model.

A page should be readable at several depths:

  • title and metadata;
  • opening paragraph;
  • headings and table of contents;
  • margin notes and linked phrases;
  • body text;
  • previews of internal pages and sidenote fragments;
  • backlinks and neighboring section pages;
  • the original source note when working in the repository.

This is the main Gwern influence. The page should not force every reader to consume every layer at full size. A skimmer can read the section headings and opening paragraph. A careful reader can open a sidenote, keep a preview window pinned, inspect a backlink, or follow the product chain. The same page should be shallow enough to skim and deep enough to reward attention.

  1. Source-shaped authoring, reader-shaped routes.

The source tree should remain honest about how the work is made. Essays live as folders under prose/, with the canonical source note at prose/<slug>/<slug>.md. Product notes live under product/<slug>/docs/ because they are product documentation in the source system. Documentation about the site lives under docs/.

The reader should not have to inherit all of that storage detail. The staging step rewrites the source into clean routes: docs/index.md becomes the site root, prose roots become prose/<slug>/, and product docs lose the storage-only /docs segment in rendered URLs. Aliases keep source-shaped links valid, but the browser sees routes that behave like a finished site.

This distinction is central. The authored vault is allowed to be useful to the writer. The rendered site has to be useful to the reader.

  1. Progressive enhancement over fragile dependence.

The site should remain readable when optional scripts fail. JavaScript improves the experience: popover windows, desktop margin-note hydration, search, theme switching, and the homepage metric count-up. But the article text, links, headings, and section structure are still emitted as static HTML by Quartz.

  1. Absence must be honest.

Shomosite is downstream of a larger private knowledge system. A published note may mention a private note, a still-unfinished draft, or a concept that has not been selected for the site. The design rule is simple: preserve the prose, but do not advertise a destination that is not there.

  1. Warmth must stay below the threshold of distraction.

The visual system is intentionally warm rather than pure grayscale: iron-gall ink on laid paper in light mode, moonlit vellum in dark mode. But the mood is carried by small choices: serif type, oldstyle numerals, restrained small caps, hairline rules, muted surfaces, and sub-pixel text-shadow. The page should feel considered without constantly announcing that it has been designed.

Architecture

The site is built from five layers.

  1. Authored source notes.

The human-editable source lives in three main folders:

  • docs/ for Shomosite’s own documentation and site-level notes;
  • prose/ for essays and essay-local notes;
  • product/ for product theses and product documentation.

These folders are not arbitrary content buckets. They express the main information architecture of the site. Prose is for arguments. Product is for systems and product ideas. Docs is for explaining the renderer and the editorial contract.

  1. The staging boundary.

Quartz expects a single content root. Shomosite’s source tree is more structured than that. scripts/prepare-content.mjs is the bridge.

It copies eligible docs into .quartz-content, mirrors docs/index.md into the root index.md, rewrites prose folder roots into folder-style index pages, flattens product docs into cleaner product routes, preserves aliases for source-shaped links, and turns essay-local notes/ files into hidden sidenote fragments under static/sidenotes/.

  1. Quartz as the static reading engine.

Quartz handles the core compilation work: frontmatter, dates, Markdown, wikilinks, tables of contents, syntax highlighting, LaTeX, search index generation, backlinks, RSS, sitemap, aliases, assets, and static page emission.

Shomosite customizes Quartz at the contract points rather than replacing it wholesale. quartz.config.ts sets the theme, transformer stack, explicit published-note filter, and custom folder renderer. quartz.layout.ts defines the shared shell, top navigation, note rails, homepage panels, footer links, and conditional placement of backlinks.

  1. Local render components.

The local components/ folder contains the site-specific layer:

  • ShomoTopNav replaces the default sidebar-first wiki chrome with a compact horizontal navigation bar;
  • ShomoHomePanels renders the homepage’s curated Prose and Product lists from frontmatter;
  • ShomoFolderContent turns /prose, /product, and /docs into semantic section maps instead of raw directory listings;
  • ShomoMarginNotes reserves the right rail for desktop margin notes on prose pages and keeps product pages structurally aligned;
  • siteData.ts centralizes the rules for slugs, titles, summaries, topics, product clusters, and curated homepage entries.
  1. Optional client behavior.

The client scripts are reading aids:

  • the popover script turns internal links, Wikipedia links, media, documents, and sidenote fragments into draggable preview windows;
  • the margin-note script hydrates prose-local notes into the right gutter on desktop;
  • the metric script animates the homepage Reach Report numbers when the panel scrolls into view;
  • Quartz’s own scripts handle search, dark mode, table-of-contents behavior, checkboxes, and single-page navigation.

The important rule is that these scripts enhance the static page. They should not become the only way to read the page.

Features

Homepage

The homepage is an authored front door, not a landing page template.

Its body comes from docs/index.md. The opening is biographical and direct, with the first two sentences set in small caps as a quiet frontispiece gesture. Beneath that, the Reach Report is a narrow editorial panel aligned to the same reading measure as the text. Its count-up animation is deliberately optional; the values are still present in the source markup.

The lower half is not a card grid. It is a two-column table of contents, manually curated through the home frontmatter field. Prose and Product are held in one shared frame so the homepage reads as one composition rather than a hero followed by unrelated widgets.

Section Indexes

The section pages are maps.

/prose groups essays by topic. /product groups product roots with their supporting docs. /docs lists selected documentation notes. These pages use the same editorial frame as the homepage but serve a different purpose: they orient readers inside the knowledge system rather than selling the site.

Note Pages

Prose and product notes share a three-zone desktop layout:

  • left rail: table of contents;
  • center: the article column;
  • right rail: prose margin notes or reserved space.

The center column is constrained because long lines punish reading. The rails exist because long-form hypertext needs peripheral structure. On narrower screens, the rails collapse and the article remains the page’s center of gravity.

Essay openings get a drop cap and a true-small-caps first line. Section headings use small caps and light rules. Metadata sits beneath the title, centered and quiet. These are old bookish gestures, but their purpose is functional: they help the reader understand where the argument begins, how sections break, and what kind of page they are on.

Margin Notes

Essay-local notes/ files are not normal pages. They are margin material.

In source, the essay links to them as linked phrase. During staging, the note file becomes an HTML fragment, and the source link becomes a preview trigger. On desktop prose pages, the margin-note script fetches those fragments and places them in the right rail beside the first rendered line of the linked phrase. If notes collide, later notes move down only enough to keep the margin readable.

On smaller screens, the same material falls back to the preview system. The content is still accessible, but the desktop margin metaphor is not forced into a layout where it no longer fits.

Previews

Previews are not decorative hover bubbles. They are small reading windows.

The popover system opens bounded windows with their own scrollable interiors. A reader can pin, drag, maximize, restore, or close them. Recursive preview stacks let a reader open context from inside context without losing the parent window. On touch layouts, previews become centered sheets.

Backlinks appear on primary note pages because arguments and product ideas should be inspectable from both directions. A normal link says “this page points there.” A backlink says “these other pages needed this page.” That second direction is essential in a knowledge system, especially one that will grow over time.

Search And Theme

Search and dark mode live in the top navigation because they are site-wide reading utilities. They are present but not dominant. The reader should be able to find them instantly and then forget them.

Dark mode is not a separate aesthetic. It is the same typographic system translated into a lower-light palette. The goal is moonlit readability, not a neon alternate brand.

The footer is deliberately small. It links to About, Design, and GitHub. It is not a second navigation system, a social proof area, or a place to repeat the site map. By the time the reader reaches the bottom, the page should end cleanly.

Implementation Contracts

Several rules keep the design from drifting into accident.

  1. A note must opt in with state: published.

The rendered site is selected, not automatic. filters/PublishedState.ts enforces this rule across sections. If a note lacks the explicit state, Quartz does not emit it as part of the site.

  1. Broken private links degrade to text.

plugins/PlainTextBrokenLinks.ts turns unresolved wiki anchors into spans. This preserves the sentence without creating false routes.

  1. Source aliases preserve authoring paths.

The staging script adds aliases when it rewrites routes. This means old source-shaped links can keep working even when the rendered route is cleaner than the source path.

  1. Sidenote fragments are extensionless.

Quartz’s static asset emitter slugifies staged HTML fragments into extensionless routes. Shomosite stages sidenote fragments that way from the beginning so preview links point at the route the browser can actually fetch.

  1. Section roots and note roots are different things.

/prose and /product are section indexes. prose/<slug>/ and product/<slug>/ are note pages. Local emitter patches preserve that distinction so nested index.md files do not accidentally become folder listings.

  1. The shell grid is semantic, not decorative.

The page wrapper, article body, rails, page footer, and site footer each have defined roles. The .center wrapper is treated as a grouping layer so the article and post-body material can participate in the intended grid.

  1. Direct-link attachments remain outside the reading corpus.

Files under attachments/ can be linked from resumes or other external documents at stable /attachments/<filename> URLs. They are emitted as files without Markdown pages, navigation entries, or search records.

  1. Tests protect the route contract.

tests/site-contracts.test.ts checks the staging rules directly: homepage mirroring, internal doc omission, prose root rewriting, product route flattening, sidenote fragment generation, asset preservation, and the published-note filter.

What The Site Refuses

Shomosite refuses the generic portfolio pattern. The first screen is not a hero slogan above decorative cards. It is authored prose and a curated table of contents.

It refuses the default digital-garden sprawl where every source file becomes a visible page. Some notes are arguments, some are margin material, some are system docs, some are private source context. The renderer has to preserve those differences.

It refuses dead-link theater. If a destination is not present, the prose should not pretend otherwise.

It refuses fragile app-dependence. A static page with optional behavior is a better base for long-lived writing than an application that must boot before the reader can read.

It refuses one-note minimalism. The site can be quiet and still have tools. The right standard is not “less interface”; it is “less unearned interface.”

Abandoned Or Deferred

Reader mode was removed from the current shell. The site already exists to be a reader mode. A second stripped view added another control without solving a real reading problem.

The old Explorer-first sidebar is gone from the primary shell. It made sense for a default Quartz wiki, but Shomosite’s main sections are few enough to fit in top navigation, and note pages need their rails for a table of contents and margin material.

Local archiving of every referenced source is not implemented. Gwern’s principle that local copies fight linkrot is still relevant, but Shomosite has not yet built that layer. For now, the site relies on ordinary links, previews where available, and the source repository as the durable authored layer.

The Reach Report is currently an authored homepage element animated by a small script. If it becomes a truth claim rather than a display element, the design rule should be that the values come from a reliable source or fail visibly instead of becoming stale decoration.

Margin-note placement remains a design tension. Exact anchoring and no-overlap can conflict when many notes point into dense prose. The current behavior favors first-line anchoring until collision, then moves later notes down. That is the right starting contract, but dense pages should continue to be tested against it.

Test Of Taste

A change belongs in Shomosite when it helps one of these things:

  • reading the text;
  • understanding the structure;
  • opening context without losing place;
  • preserving the source contract;
  • making absence honest;
  • keeping the site fast and durable.

A change is suspect when it merely makes the site look more designed.

The site should feel like a page that has learned from old books, wikis, and personal knowledge systems without pretending to be any one of them. It should have Gwern’s seriousness about hypertext, but Shomo’s own structure: Prose for arguments, Product for systems, Docs for the renderer’s self-knowledge.

That is the design: not a theme, but a compact reading machine for a growing body of thought.

Backlinks