A widget in this theme's widgets/ folder is one of two things.

Static — a figure.html and nothing else. It renders once, at build time, and stays that way forever; there is no matching widget.js to hand off to. That is the whole widget below:

Interactive — a widget.js that registers itself with Taiga.widget(id, fn), usually paired with a figure.html that stands in until JS runs, and a widget.css for anything the theme's own building-block classes (.w-row/.w-btn/.w-num/.w-cap) don't already cover:

Both are the same {{< widget id="…" >}} shortcode with no inline body — the id is all it takes for the shortcode to go looking for widgets/<id>/figure.html as the page resource to fill the mount with. See "A guide is a folder" for the other form, an inline fallback written straight into the shortcode.

#The _shared layer

Both widgets above load widgets/_shared/lib.js and widgets/_shared/shared.css before their own files — the build sorts every widgets/**.js and widgets/**.css of a bundle by name, and _shared sorts ahead of any w-* folder. Concretely, in this bundle:

• _shared/lib.js holds the one guard (var W = window.Taiga; if (!W || …) return;) that every widgets/<id>/widget.js in the bundle relies on, plus a tiny h() element builder that w-anatomy-toggle/widget.js calls without importing or redeclaring it — they're concatenated into one script and share a scope.
• _shared/shared.css holds .wa-tag, the little pill both widgets above use to label a filename. It earns its place in _shared for the least exotic reason there is: two widgets on this page actually use it.

Nothing here is shared out of necessity — a bundle with one widget could just as well put the guard straight into widgets/<id>/widget.js. It's split out on purpose, so this page has an _shared/ to point at. A bundle where the split carries real weight looks the same in shape, just heavier: a shared engine and its spec table sit in _shared/lib.js, and every id that engine drives gets its own widgets/<id>/ folder for whatever is genuinely its own — a figure, a widget.css override, sometimes nothing at all.

#Reading the source

The whole bundle, next to this file:

widget-anatomy/
  index.md, index.ru.md    ← this text, in both languages
  widgets/
    _shared/
      lib.js               ← guard + the h() helper
      shared.css            ← .wa-tag
    w-anatomy-static/
      figure.html           ← the whole widget — no widget.js
    w-anatomy-toggle/
      figure.html           ← no-JS fallback
      widget.js             ← Taiga.widget('w-anatomy-toggle', …)
      widget.css             ← .wa-hl, only this widget's class

Every file in widgets/ is optional except the ones that give a widget its substance: a static id needs figure.html, an interactive id needs widget.js, and either can add a widget.css. A widget can also skip figure.html entirely and start from an empty mount — w-ks-counter on the "Kitchen sink" page does exactly that.

Keys are bound to physical key codes, not characters — they work in any layout, including Russian. They don't fire inside input fields; focus mode only applies on article pages.

#Panels and minimaps

A hidden panel doesn't disappear completely — it collapses into a minimap at the edge of the screen: dots and dashes mirror its content. Hovering expands the panel over the text, and you can pin it back from there. Read parts of a series get marks — so you can see where you've already been.

#The "View" popover

The icon in the top-right corner opens the reading settings: palettes with swatches, toggling the side panels on and off, the list layout variant on rubric pages. The header has no separate setting: it always slides away on scroll down and comes back on scroll up.

#What gets remembered

All settings live locally in the browser — no accounts, no network:

Clearing the browser's site data resets everything to defaults — that's the standard way to "reset settings."

The signature color of a site is a toml file in data/themes/ on the site side:

name = "Mine"     # the name in the picker
weight = 80       # position in the picker's list

"bg-deep" = "#101418"
"bg-surface" = "#1a2027"
"text-primary" = "#d8dee6"

Hugo merges the data of the theme and of the site (on a name clash the site wins), so the file finds its own way both into the CSS and into the palette picker in the header. Don't need one of the palettes the theme ships with — override its file with disabled = true, and it disappears everywhere. How CSS blocks and swatches come out of the toml is taken apart in "A palette is one file".

#custom.css and hooks

Pointed edits on top of the palette go into the site's assets/css/custom.css: if the file exists, the theme appends it last to the CSS bundle, so your rules win without !important. The design tokens are a public API: the names of the CSS variables are stable and are listed in the theme's docs/customizing.md.

For analytics, meta tags of your own and third-party scripts there are hook partials: hooks/head-extra.html and hooks/foot-extra.html are empty in the theme, the site puts files of the same names into its layouts/_partials/ — and their contents land in the head and at the end of the body. And if the render itself needs changing — any partial of the theme is overridden by a site file of the same name: Hugo's lookup order always prefers the site's files. The small named partials — the logo, the footer, the feed card — exist for exactly this kind of pointed override.

#A section of your own

You need a section the theme does not have — a glossary, a catalog, a playground with a drill. It needs neither a new layout nor edits to the theme: it is an ordinary page or bundle, and the interactivity is the same widgets.js next to the text — the mechanism works for any bundle, not only for guides. A menu item is added to [[menus.main]] in the config; the item's params.badge = "β" draws a badge — that is a generic feature of the navigation, not the mark of a special section.

The "Playground" on this demo is built exactly that way: in the theme there is not a trace of it, the whole section is three files on the site side.

#Strings of your own

The texts of the interface are not hardcoded in the templates. The server-side strings live in i18n/*.toml: the site puts down its own file with a partial set of keys, and it merges with the theme's file — you override only what you need. Strings that live in JS — the "View" popover, the hints of the minimap — are overridden with the window.THEME_I18N object; the list of keys is in docs/customizing.md.

#A second language

Adding a language is an additive step, not a migration. A [languages.ru] block is written into the config (plus [languages.ru.params] for the hero line and [languages.ru.menus] for the menu). The translations come as file suffixes: index.ru.md next to index.md, including the _index of the rubrics and the series; Hugo pairs the versions itself. A language switcher appears in the header when the site has more than one language, and Pagefind builds a separate index per language, by the page's lang. Template edits: zero. The step-by-step checklist is in the theme's docs/i18n.md.

This page is the proof: you are reading the English version, and the Russian one lies next to it as index.ru.md.

You can now take your site as far from this demo as you like — without forking the theme.

#What's next

The handbook ends here: the theme is installed, guides are being written, the site looks like its own. If you are curious why it is built this way, "Inside" has the "Anatomy of the theme" series: the leaf bundle, the arithmetic of series, palettes-as-data. And every component at once is laid out on the kitchen-sink page in "Reference".

hugo new content guides/my-first --kind guides

The guides archetype creates a leaf bundle: an index.md with the front matter skeleton filled in, and a starter widgets.js beside it. Files that lie in the guide's folder are picked up by the theme itself — nothing to wire up.

#Front matter: what to fill in

title: "My first guide"
description: "One sentence — for the feed, for search and for meta."
lead: "The lead paragraph under the title; it may run longer than description."
tags: [example, setup]
mins: 4
version: "v0.0.1"

The two highlighted fields have non-obvious rules. mins is a handwritten, honest estimate of reading time: it lands in the article's chips and in the arithmetic of the series, which is why it is not trusted to an automatic count (omit the field and the theme will count for you). version is an arbitrary string for the version chip: the version of a language, of a DBMS, of your product — the theme renders it as-is. The archetype fills in date and slug too; the date lives only in the feed and the RSS — it appears nowhere in the text of the article.

A guide becomes a series part by where it lives: its folder sits inside the series folder (guides/track/my-part/), and weight sets its order among the parts; rail_title gives the panel its short name. How "part N of M" comes out of that is taken apart in "A series knows itself".

Mark up headings with explicit anchors: ## Section {#section-id}, in Latin letters — then links and the table of contents do not depend on how the heading text transliterates. That matters the day the page gets a translation.

#Shortcodes

Four of them, and that is enough for most guides:

• callout — an inset; types key, trap, internals, note;
• widget — the mount point of a live illustration (below);
• raw — a multi-line HTML fragment as-is, for diagrams;
• bigcard — a large card link to a neighboring piece.

{{< callout type="trap" label="Trap" >}}
Inside it — plain markdown.
{{< /callout >}}

Code blocks take attributes right in the fence: ```toml {label="config.toml (fragment)", hl_lines=[2]} — label draws a caption above the block, hl_lines highlights lines. You have met both already in this article: the caption on every block and the highlighting in the front matter example are done exactly this way.

#A widget in two touches

A live illustration is added without editing the theme. Touch one — the shortcode in the text; inside it goes a static fallback, which is what readers without JS are left with:

{{< widget id="w-demo" note="— a task for the reader" >}}
<p>A static fallback for readers without JS.</p>
{{< /widget >}}

Touch two — an initializer with the same id in the widgets.js next to index.md:

Taiga.widget("w-demo", function (root) {
  root.innerHTML = "";
  // you build the widget out of the theme's building-block classes:
  // .w-row, .w-btn, .w-num, .w-cap — no styles of your own needed
});

The theme's runtime waits for the DOM, finds the mount point and calls the callback inside a try/catch: a widget that falls over writes to the console and does not bring the page down with it. The one thing to watch is that the id in the shortcode and the id in Taiga.widget(…) match letter for letter.

Here is the working proof — an estimate of an honest mins for a guide not yet written:

It is built exactly as in the examples above: the shortcode here, Taiga.widget("w-mins", …) in the widgets.js in this article's folder.

You can now write a guide with a live illustration without opening a single file of the theme.

#What's next

The guide exists, the site builds — but it still looks like this demo, not like your project. The third part is about a palette in one file, custom.css, sections of your own and a second language.

A theme for learning guides that are read in order, not at random. Content sits on three levels: rubrics → series → guides. A series is a folder inside its rubric — membership is where the guide lies; everything else — "part N of M" in the kicker, the panel with the table of contents on the left, the bridge with "~N min left" at the bottom — is counted at build time. A guide is a folder: its interactive widgets, styles and cover lie next to the text, and it moves as a whole, one folder. Everything you see on this demo — the feed, search, palettes, cover generation — is a stock mechanism of the theme: the demo is built on nothing but it.

Two binaries, and that is the whole toolchain. The first is plain hugo, not extended: there is no Sass in the theme, and esbuild for JS is built into the standard binary. The second is pagefind, full-text search over the built site. Node, npm and node_modules take part in neither the build nor development. The minimum Hugo version is declared in the theme's config: a binary that is too old stops the build with a clear error rather than with strange behavior.

#Three ways to install

The paths below are placeholders: substitute the address of the theme's repository.

Hugo Module — the main way. Into the site config:

[module]
  [[module.imports]]
    path = "github.com/user/theme"

Then hugo mod get -u (if the site is not a module yet — hugo mod init github.com/user/site, once). Versions resolve against the theme's semver tags; to edit the theme locally, use a replace in the site's go.mod.

Git submodule — if you would rather not have modules:

git submodule add https://github.com/user/theme themes/theme

plus theme = "theme" in the config. In CI, do not forget to check out with submodules: recursive.

A copy in themes/ — a clone or an unpacked archive in themes/theme, plus the same theme = "theme". Updates are manual; on the other hand this is the way to look at the theme with no commitment.

#The minimal config

baseURL = "https://example.org/"
title = "My handbook"
theme = "theme"                # not needed when installed as a module
defaultContentLanguage = "en"

[languages.en]
  languageCode = "en"
  languageName = "English"
  weight = 1

[taxonomies]
  tag = "tags"

[[menus.main]]
  name = "Guides"
  url = "/guides/"
  weight = 10

The [languages.en] block looks redundant while there is one language, but it makes adding a second one an additive step rather than a config migration. The rest of the behavior is tuned through [params] — the home hero line, how many feed posts are visible, the "guide of the week", the default palette — and everything has a default: the site builds without a single param. The full registry is in the theme's docs/params.md.

#Content layout

content/
├── _index.md              # home: the hero line and data
└── guides/
    ├── _index.md          # rubric: label, lead
    ├── my-first/
    │   └── index.md       # a standalone guide = a folder (leaf bundle)
    └── track/             # a series = a sub-folder of the rubric
        ├── _index.md      # series metadata: title, description
        └── part-one/
            └── index.md   # a part — the same guide folder, one level deeper

The section names are yours: the theme deals in "sections", "series" and "guides" and hardcodes neither rubric names nor subject words. A handbook about databases and a handbook about watercolor lay out the same way.

#Build

hugo server                        # development
hugo && pagefind --site public     # production: site + search index

There are two commands because pagefind indexes a site that is already built. Search does not break in dev without an index: the modal quietly tells you which command builds it.

You can now stand up a site on the theme from scratch and build it in one pass — all that is left is to fill it.

#What's next

An empty site builds, but there is nothing to show yet. The next part is about the first guide: a scaffold in one command, the front matter canon and a live widget in two touches.

Level two — with the # character, level three — with ##. Inline: italic, bold, code, an internal link to the reference guide.

##Third-level subheading

Checks that render-heading attaches ## and an anchor to h3.

#Code

Go is highlighted server-side (Chroma in the palette's colors):

type Point struct {
	X, Y int64
}
func dist(a, b Point) int64 { return (a.X-b.X)*(a.X-b.X) }

With a file caption and line highlighting ({label=… hl_lines=[2]}):

func mallocgc(size uintptr) unsafe.Pointer {
	c := getMCache()          // hot path — no locks
	return c.alloc(size)
}

Other lit languages wear the same roles — blue for a structural name, copper for a number, one tone for strings, muted italic for a comment:

{
  "items": [
    {"price": 123, "shipped": true},
    {"price": 101}  // a trailing comment is fine
  ]
}

export GODEBUG=schedtrace=1000
go build ./... && ./app --addr "$HOST:8080"   # both, or nothing

A bare fence, text or txt is the plain form — flat .nohl, which is what a transcript wants:

$ go build ./...
ok  taiga/internals  0.312s

#Table

A Markdown table; render-table attaches the .tbl-wrap wrapper:

#Callouts

#Fold

A collapsible inline note — icon, summary, and a toggle; the panel slides open by height. title= is inline Markdown, the body is Markdown.

func main() { println("hello") }

Past roughly half a screen of prose the fold switches register on its own: the summary is set at reading size, the block takes its own air, and the panel ends with an explicit toggle so a long aside can be closed from where the reading stopped. size= forces either register — here it is used to show the section one without pasting a wall of text.

#Terms

Hover an underlined word and its definition opens as a card; a click pins the card so you can read it and follow the link inside. With JavaScript off every definition sits as a list at the foot of the page, and each word links to its own.

The plainest form — a word and a definition, default type: every P owns an mcache, and hitting it is the cheapest allocation there is.

With a type label, its colour, and a link in the card's footer: the compiler inserts a write barrier — which is why a pointer write costs more than an int write.

A definition renders through the same pipeline as the article, so a listing inside a card is lit exactly as it would be in the prose: the path is a JSON Pointer, not a dotted path.

When the word reads differently in the sentence than it should in the card's heading, title= splits the two: the data lives in the core's caches, not in RAM.

#Diagrams

A memory diagram and a byte strip — raw HTML via {{< raw >}}:

#Widgets

Form 1 — an empty mount, brought to life by Taiga.widget from widgets.js:

Form 2 — a mount with a static fallback inside (visible without JS):

Form 3 — no id, arbitrary HTML directly in the figure:

#Card

#Link previews

On a fine pointer, hover any link below to see its preview card — the physics of the term card, one popover, built from a build-time fragment (internal) or a pre-rendered card (Telegram, YouTube).

Internal links open a window into the page: a whole guide preview, a section anchor that scopes the card to one section, and a series index that lists the parts.

Telegram — a post from the author's own channel earns a card scraped at build time: post 409 and post 410. A missing post degrades to the channel card, and a foreign channel gets only the ✈ mark, no card.

YouTube — a talk on the Go scheduler opens a video card with its thumbnail, duration and view count.

An ordinary outbound link carries only the ↗ mark.

Wikipedia — a work-stealing scheduler and preemptive multitasking each open a summary card built from Wikimedia's REST API, carrying the W mark.

The Go blog — a preview of loop-variable scoping and the classic error handling in Go open a card with the italic Go mark, the byline and the post's opening.

#Newsletter

The subscription blocks, on a site that runs a newsletter (params.newsletter.enable — newsletter.md). This demo has no endpoint behind them, so a submission ends in the error state — which is itself the degradation worth seeing.

The mid-text block, placed by hand, with a close button (dismiss=) whose verdict is remembered per block:

The bare form for a page written as prose (newsletter-inline), the same component the subscribe page uses:

The card at the foot of this page is the third one — newsletter-cta, inserted automatically here by placements.articleEnd.

The naive model: covers for sharing are drawn by hand. By the thirtieth article that is a pain, and after a title is renamed it is twice the pain: the picture now lies, go redraw it.

Here the build generates the covers, and the look is described by a style — a folder in assets/og/, folder name = style key. Two files inside are mandatory: base.png, the 1200×630 backdrop where all the graphics live, and layout.toml, the layout of the text blocks on top of it:

[[block]]
text = "{title}"
font = "Inter-ExtraBold.ttf"
size = 66
color = "#e6dfd2"
x = 76
y = 270
width = 1010     # long titles wrap on their own

The placeholders — {title}, {kicker}, {meta}, {domain}, {part} — are assembled by a partial, so a style is language-neutral: the texts come from the article, the layout from the style. Blocks are drawn in order; unknown keys are ignored — an old style survives a new version of the theme. The optional home.png is a fully baked poster for the home page and the rubrics; without it, the shared cover is generated from base.png by the same pipeline. And a folder with no layout.toml simply does not count as a style.

The style is chosen with the site param ogImages.style, and for a single page with og_style in the front matter. On top of any style the author's override works: drop an og.png into the article's bundle and the generator gives way to your picture. A site adds a style of its own with a folder: the theme's assets and the site's are merged, and the site wins.

#Search that reads everything

The naive model of search on a static site is an index of titles and descriptions: it finds an article by its name and stays silent about a term from the middle of the text. The engine here is a different one: Pagefind builds a full-text index over the already-built site. Which is why a build is two commands:

hugo && pagefind --site public

Pagefind is a standalone binary; Node is not needed. It walks the finished HTML and takes only what the theme marked up: the body of the article in full, the breadcrumb and the minutes for the result card as separate metadata, while panels, widgets and the rest of the chrome do not get into the index at all. Code blocks are indexed with a lowered weight: a search by function name has to work, but code must not clog the results. Stemming comes out of the box, by the language of the page: a query for "covers" finds "cover", and on the Russian version of this page the Russian morphology does the same job. The search script and the index itself load lazily, on the first opening of the modal: search nothing and you download not a byte.

Check it on this page: open search and type a word from the middle of the text — "monospace", say. It will be found, with highlighting and an excerpt. And if you run a bare hugo server without the second command, the modal honestly tells you what builds the index — quietly, without red errors.

#The version chip

The meta of this article carries a "v0.0.1" chip. The theme has no idea what that means: the chip is an arbitrary string from version in the front matter, or, if the field is absent, from the site's versionDefault. A site about a programming language writes the version of the language there, a site about a database writes "PostgreSQL 17", and this demo writes the version of the theme itself — and the theme renders all of it the same way, as-is. A small detail, but agnosticism is made of exactly these: the theme does not know what your site is about.

You can now build a site with covers and full-text search in two commands — and explain why there are exactly two.

#What's next

That was the view from outside — what the build does for the reader. The view from inside — how the pages themselves are put together — is in the "Anatomy of the theme" series: leaf bundles, the arithmetic of series, palettes as files.

The naive model: I want to repaint the site my way — I'll open the theme's CSS and change the colors. The pain arrives with the very first theme update: your edits lie in its files, and every update is a merge conflict. The classic choice of "fork it and drop off upstream — or put up with somebody else's colors". Both options are bad, and both grow from one mistake: color is treated as styling, when in fact it is data — a table of "variable name → value" that has nowhere to live except somebody else's CSS.

#One toml

Here a palette is data, not styles. Each one is a file data/themes/<id>.toml: a couple of housekeeping fields plus color variables whose keys are literally the names of the CSS variables without the --:

name = "Mine"     # name in the picker
weight = 80       # position in the picker's list

"bg-deep" = "#101418"
"bg-surface" = "#1a2027"
"border" = "#2b3138"
"text-primary" = "#d8dee6"

Highlighted are the only two lines that are not CSS variables. All the rest is a straight "name → color" table. The key ones:

At build time the partial head/palettes.html turns these files into CSS: a :root { … } block for the default palette plus one [data-theme="<id>"] { … } block per palette — and pours the result into the common CSS bundle first. Which palette is the default is decided by the site parameter defaultTheme: it is just the id of one of the files. Switching the theme is switching one data-theme attribute on <html>; the cascade does the rest. That is also why the switch is instant: the browser has nothing left to fetch, every palette is already in the CSS it got with the page's first byte.

#The picker and its JSON

Where does the picker learn which palettes exist? From the same data: the partial puts a <script type="application/json" id="dg-themes"> on the page with a list of {id, name, group, weight, swatch colors} — the swatches are taken from four fixed keys of the palette (bg-deep, bg-surface, text-primary, text-muted), so the thumbnail in the picker honestly shows the canvas, the card and the text to come. The popover in the header reads that list and draws the buttons. The widget below reads the very same list — and on a click sets the very same attribute:

Notice the honest difference: the widget changes only the attribute, while the picker also writes the choice into storage — which is why after a reload its version wins. And the saved choice is applied before the first paint, by a tiny inline script in <head>: the page does not flash the default palette, not for a single frame.

Now the main thing — extensibility. Your site needs a house palette? Put data/themes/mine.toml on the site side: Hugo merges the theme's data with the site's (the site wins on a name clash), and the file finds its own way into both the CSS and the picker. Don't like a palette that ships with the theme — override its file with disabled = true, and it disappears everywhere. Not a line in the theme, no fork.

Now you can give a site a palette of its own with one file — without touching the theme's CSS, JS or templates.

#What's next

The "Anatomy of the theme" series ends here: a guide is a folder, a series is a folder of guides, a palette is a file. Everything shown — and a dozen components we never got to — is gathered on one proving-ground page:

And as for what happens at build time — covers, search, the version chip — there is a deep dive of its own in "How-to".

The naive model: a series is when every article ends with a list of links to the rest. It works right up to the second change. Add a fourth part — go update three old articles. Reorder the parts — "part 3 of 7" in the headings now lies, and lucky you if you remembered all seven. Contents smeared across the articles go stale the moment you edit anything — because there are as many sources of truth as there are parts.

Worse: half of the series machinery cannot be expressed by hand-written links at all. "~9 minutes left to the end of the series" is arithmetic over every part at once; no article knows that about itself alone.

#A folder, not a field

Here a series has one source of truth. A part declares almost nothing about itself — it simply lies in the series folder, a sub-section of the rubric:

content/inside/
  anatomy/                  ← the series
    _index.md               ← series metadata: title, description, order
    guide-is-a-bundle/      ← part, weight: 10
    series-knows-itself/    ← part, weight: 20 — you are here
    palette-is-a-file/      ← part, weight: 30

This is the folder of the article you are reading — check it against the kicker above the title. Membership is location; the one thing a part carries itself is weight in its front matter, its order among the parts. Everything else is computed at build time: the parts are sorted by weight, the "N" is the position in the sorted list, the "M" is its length. Notice: the order is set by weight, not by publication dates — you can reorder the parts without rewriting the feed's history.

From that same sorted list everything series-shaped on the page is assembled. The kicker is glued from three independent sources: the rubric label (the section's front matter), the series title (the front matter of the series' _index.md) and the computed "part N of M". The panel on the left is the contents with the current part marked. The bridge at the bottom is the prev/next neighbors plus a progress scale. One list, four consumers.

Here is our series through the eyes of the build:

The highlighted cell is the article you are standing inside. Hover the neighbors: each tooltip carries its weight and its minutes.

The series title, its description and its order on the rubric page are no magic either: that is the front matter of the folder's _index.md — here, content/inside/anatomy/_index.md (scaffold one with hugo new content inside/anatomy/_index.md --kind series). The same file gives the series a landing page at /inside/anatomy/: the title with its tagline, the description, the file's own body as an epigraph, the list of parts and a "start the series" button. The "whole series" links in the panel and the bridge lead exactly there; on the rubric page the same series stands as an anchored block. And a series announced with an _index.md but no parts yet is not an error: the rubric shows it as an "in the works" teaser, and its landing renders the announcement.

#Check the arithmetic

The bridge's formula is short enough to recompute right here. The widget below runs the same logic over the numbers of this very series:

Notice: the numbers in the widget match the diagram above and the real bridge at the bottom of the page. That is the point — all three have one source.

And what about articles outside series? They get the same kicker, only instead of "part N of M" it says "deep dive", and the panel on the left is filled from the related field in the front matter: three to five links to nearby guides. A series is an option, not an obligation.

Now you can assemble a series out of any guides by gathering them into one folder — and reorder the parts by changing one weight, not N articles.

#What's next

The bridge below has already worked out that one part is left. It is about color: why all seven palettes of this page live in data files, and how to add your own without touching a line of the theme.

The naive model goes like this: I'm writing a text, and at one spot I need an interactive illustration. A button, a counter, anything. Feels like ten lines of JS.

Now the pain. In an ordinary theme there is nowhere to put those ten lines. The script has to be wired into <head> — so you edit a template. The template is shared — so the script ships to every page at once. To stop it, you need a registry of which script belongs to which page — so you add config. A month later you have three articles with widgets and one template file nobody dares to touch. The text lives in one place, its code in three others, and you can no longer move the article as a whole: it has grown roots into the theme.

#An article is a folder

Here an article is a leaf bundle: a folder that holds everything it owns. Here is the file strip of the bundle — the very folder this page was built from:

Only index.md is required. Everything else is an optional neighbor: drop widgets.js beside it and the theme finds it, minifies it, fingerprints it and wires it in on this page only. Drop widgets.css — the same for styles. Drop og.png — the social cover is taken from you instead of being generated.

#Two touches

The full cycle of "add a live illustration" is two touches. First: in the text you place a shortcode with an id and a prompt. Second: in widgets.js you register an initializer with the same id:

Taiga.widget("w-hello", function (root) {
  root.innerHTML = ""; // drop the static fallback
  // …button, counter, badge — all the code in the file next door
});

No templates, no <head>, no registries. The shortcode has a paired form: inside it goes a static fallback that lives in the mount point until JS replaces it — and if JS is off, it stays for good. A page without scripts degrades into meaningful text, not into a hole.

Notice what the example above does not have: styles of its own. The building-block classes — .w-row for a row of controls, .w-btn for buttons, .w-num for a big number, .w-cap for the output line — live in the theme's CSS, and the widget looks native without hauling in a single rule of its own. widgets.css is needed only when that set runs out — and then it, like everything else, simply goes into the folder.

#The runtime catches the fall

Taiga.widget is a small runtime in the theme. It waits for the DOM, finds the mount point by id and calls your callback wrapped in a try/catch: a widget that throws writes to the console and does not take its neighbors down. And if there is no mount point — the shortcode was taken out of the text — the initializer is skipped in silence.

Now check all of it on a live specimen. The widget below was mounted by that very runtime, out of that very widgets.js that lies in this article's folder:

One last thing: the mechanism is not tied to guides. widgets.js is picked up from any bundle — an interactive page here is not a separate type with a template of its own, but an ordinary markdown page with a script lying next to it.

Now you can add a live illustration to any guide without opening a single file of the theme.

#What's next

This article is part of a series, and the panel to the left of the text already carries its contents, while the kicker says "part 1 of 3". Nobody typed that by hand. Where the theme knows it all from — in part two.