A Zoo of Article Blocks
Every block a personal site tends to want, rendered beside the source that made it — and a note on which needed engine features and which needed only a template.
সূচিপত্র
A Zoo of Article Blocks
Each block below shows its source and then itself. None of them needed an engine change: :::name{k=v}
accepts any name and renders through a theme fragment of that name, so a block library is a file of templates
plus a stylesheet. Every one below is khata’s now, which draws them on every site — verse, the epigraph, the dated
notice, :abbr, the highlights — so a theme of your own copies the define and the partial it wants. The classes an
author writes, at the foot, are styled by this page alone, through styles: in its frontmatter.
The reference theme deliberately carries none of this — it demonstrates the contract, not a design.
Verse
Poetry needs its line breaks kept, and its indents.
:::verse{by="nobody in particular"}
The rain came down in sheets,
then stopped, as if embarrassed.
Three lines. Three breaks.
:::
The rain came down in sheets, then stopped, as if embarrassed. Three lines. Three breaks.
goldmark keeps the newline inside the paragraph, but not the indent a line began with: khosra puts that back for
every container’s lines (ADR-9015), and khata’s white-space: pre-wrap shows both. No trailing double spaces, no
<br> in the source.
Pull quote
This one graduated: khata carries pullquote itself now, hung half out of the column beside running prose —
In the Margins shows it where it belongs. Here it has no prose to hang beside, so it is
{centred} across the column instead (Where a Block Sits has the other places).
:::pullquote{centred by="The paragraph above"}
A sentence worth setting apart at display size.
:::
Epigraph
:::epigraph{by="Borges, probably"}
I have always imagined that Paradise will be a kind of library.
:::
I have always imagined that Paradise will be a kind of library.
Columns
Every top-level block of the body is one column, so the call carries no count and no separator. The block also widens past the measure — a column of code needs the room — and how many columns fit is CSS’s decision, not the author’s: below about 14rem a column stops being worth reading, so they stack rather than shrink.
Unlike the rest of this page, columns lives in the theme rather than in this site’s overlay. It is a block
the production theme carries, and the demo shows it rather than redefining it.
:::columns
Left. Ordinary Markdown, including **emphasis** and lists.
Right. Stacks under the left on a narrow screen, which is CSS's decision.
:::
Left. Ordinary Markdown, including emphasis and lists.
Right. Stacks under the left on a narrow screen, which is CSS’s decision.
Three blocks are three columns. A fourth wraps onto a second row rather than crushing the rest.
:::columns
**Fetch.** Pull the archive down from the settings page.
**Strip.** Drop the assignment so the file parses as JSON.
**Post.** Replay the ids against the endpoint.
:::
Fetch. Pull the archive down from the settings page.
Strip. Drop the assignment so the file parses as JSON.
Post. Replay the ids against the endpoint.
A column wanting several blocks wraps them in :::col, and the outer fence grows a colon so the inner ones
close first (ADR-0117). This is also how a column holds another call — a note, a figure, or a nested :::columns
that subdivides its own track.
:::::columns
::::col
### Before
The archive ships the tweets as an assignment.
:::callout{note}
One file per part, all of them the same shape.
:::
::::
::::col
### After
Strip the assignment and it is plain JSON.
::::
:::::
Before
The archive ships the tweets as an assignment.
After
Strip the assignment and it is plain JSON.
A :::columns inside a column subdivides that column’s own track rather than reaching for the page again.
::::columns
Whole, on the left.
:::columns
Top right.
Bottom right.
:::
::::
Whole, on the left.
Top right.
Bottom right.
Callouts
One call for every box beside the text: callout, with two words in its braces — what it is and how it is
drawn, either or both, in any order. Nothing in the engine knows any of these words; each is the theme’s. Every kind
in every form, in English and Bengali: Callouts, Every Way.
What it is
The kind sets the mark, the colour and the word a box is headed by.
:::callout{note}
The gauge is read at nine every morning.
:::
How it is drawn
The same warning in every form: the soft box (no word), window, tinted — with and without a title — run-in
and hanging.
:::callout{warn window}
A gauge under a tree reads low all season.
:::
:::callout{warn tinted}
A gauge under a tree reads low all season.
:::
:::callout{warn run-in title="Placement"}
A gauge under a tree reads low all season.
:::
A changelog
hanging and the four changelog kinds, a run of them close together; a date where one is given.
:::callout{added hanging on=2026-06-01}
A second gauge, on the roof's north edge.
:::
:::callout{fixed hanging}
June's figures: the first draft read millimetres as centimetres.
:::
Chips
Inline, a word or two in a kind’s colour and mark: the new gauge is beta, the reading confirmed, the old funnel gone, and a plain one draft.
the new gauge is :callout[beta]{warn}, … a plain one :callout[draft]
A dated notice
:::callout{on=2026-04-02}
Corrected the gauge figures: the first draft read millimetres as centimetres.
:::
A number worth its own line
One of khata’s highlights; Highlights shows them all.
:::stat{label="millimetres, June to September"}
2,431
:::
2,431
Timeline
A description list with a rule down its side, so a screen reader hears terms and descriptions rather than a
decorated div. khata carries timeline itself now, with a second, long form — see
A Decade of Gauges.
:::timeline
2024
: The first gauge, bought secondhand.
2025
: Three more, and a notebook.
2026
: This site.
:::
- 2024
- The first gauge, bought secondhand.
- 2025
- Three more, and a notebook.
- 2026
- This site.
What a callout actually holds
A callout’s body is a block — paragraphs, lists, code, figures, and other calls. The fence is longer on the outside so the inner one closes first (ADR-0117).
::::callout{warn title="Before you run this"}
It rewrites files in place. Two things to check first:
1. The gauge log is committed.
2. You are not in `/`.
:::callout{tip}
`--dry-run` prints what it would do and touches nothing.
:::

::::
A callout is a container like any other, so nothing above is a special case: the list, the nested tip and the figure are the same mechanisms that work anywhere else.
Folded sections, with no JavaScript
details is already in the reference theme, and group= makes several mutually exclusive through the native
name attribute: opening one closes the others, an accordion. Tabs, picked from a row of titles, are ::::tabs.
:::details{summary="Show the workings" group="one"}
Grouped panels close each other. No script involved.
:::
Show the workings
Grouped panels close each other. No script involved.
Or these workings
Because name is the browser’s own mechanism for exclusivity.
Code, which the engine already frames
A title, line numbers, a starting offset and highlighted lines are all engine options — code.go reads them and
the theme frames the result.
```go {title="rank.go" numbers=1 hl="2-3"}
func score(b content.Publication, terms []string) int {
title, body := tally(tokens(b.Title)), tally(tokens(string(b.Body)))
total := 0
return total
}
```
1func score(b content.Publication, terms []string) int {
2 title, body := tally(tokens(b.Title)), tally(tokens(string(b.Body)))
3 total := 0
4 return total
5}
Code inside a sentence names its language the way a fence does, with the word in braces straight after it — so
`tally(tokens(b.Title))`{go} reads as tally(tokens(b.Title)), in the fence’s colours and the sentence’s
size (khosra ADR-0480). A word no lexer knows leaves the span plain and the braces showing, and khosra check names
it.
Structures for prose
A scene break needs no block: khata draws a line of three dashes between two paragraphs as one, an asterism in a wider gap rather than a rule across the column:
The gauge was left to itself for the night.
---
By morning the roof was a lake.
The gauge was left to itself for the night.
By morning the roof was a lake.
Dialogue is khata’s :::chat — a line to each turn, set as a definition list, so a screen reader hears speaker and
speech rather than a decorated box. With no options it is a transcript, names in a column as a play’s script sets them; bubbles makes it
a messaging thread (In the Margins uses it):
:::chat{cast="r=Ruma a=Abbas"}
r: You measured it wrong.
a: I measured it twice.
:::
- Ruma
- You measured it wrong.
- Abbas
- I measured it twice.
A letter, on ruled paper, with whatever of place, date, to and from you give it — to is the greeting as
you would write it, and takes its comma:
:::letter{place=Kalabagan date=2026-08-12 to="Dear Ruma" from=A.}
The gauge is yours if you want it. I have stopped writing the numbers down.
The funnel is on the shelf by the stairs, still level.
:::
Kalabagan,
Dear Ruma,
The gauge is yours if you want it. I have stopped writing the numbers down.
The funnel is on the shelf by the stairs, still level.
A.
An email, as a mail client opens one — subject, from, to, cc and date, each only if you give it:
:::email{subject="Re: the gauge" from="Ruma <ruma@example.com>" to=A. date=2026-08-14}
Took it. It reads 2 mm already, and it has not rained.
Is it meant to do that?
:::
Re: the gauge
- From
- Ruma <ruma@example.com>
- To
- A.
- Sent
- Subject
- Re: the gauge
Took it. It reads 2 mm already, and it has not rained.
Is it meant to do that?
And the mark a printed essay closes with, which needs no call any more: khata sets one at the end of every titled piece’s last line by itself — this page’s included.
Two languages side by side
This is what nesting was worth fixing for. The outer fence is longer, so each :::col is a container of its
own instead of the end of the outer one — and a container that closes early used to delete its inner text. khata’s
:::columns lays them out, and lang= on a :::col says which language the column is in.
:::::columns
::::col{lang=en}
:::verse
The rain came down in sheets,
then stopped, as if embarrassed.
:::
::::
::::col{lang=bn}
:::verse
বৃষ্টি চাদরের মতো নেমে এল,
তারপর থেমে গেল, যেন লজ্জা পেয়ে।
:::
::::
:::::
The rain came down in sheets, then stopped, as if embarrassed.
বৃষ্টি চাদরের মতো নেমে এল, তারপর থেমে গেল, যেন লজ্জা পেয়ে।
Three levels, and each one is doing work: columns lays them out, col carries the lang, and verse keeps the
line breaks — which a poem needs and a prose column must not have. Five colons on the outside, three on the inside,
one per level of depth.
The lang attribute is not decoration: it is what a screen reader switches voice on and what the browser picks a
font and hyphenation dictionary from. Written by hand it would be raw HTML on every stanza.
Inline marks
:name[text]{args} is the third form of the same syntax — inside a sentence rather than on a line. The reference
theme ships several — lang, because a bilingual page is mixed sentence by sentence, and kbd, icon, meta,
human-made and checked beside it.
The word for water is :lang[জল]{tag=bn} there.
Press :kbd[Ctrl] then :kbd[K].
Text is stored in :abbr[NFC]{title="Normalization Form C"}.
The word for water is জল there. Press Ctrl then K. Text is stored in NFC.
A claim with a shelf life can carry its own date, which is the reference theme’s checked (ADR-0364):
The default derivation is Argon2id :checked[2026-09-25].
The default derivation is Argon2id .
The brackets hold the date and nothing else. The word around it, the numerals and the word order come from the
engine’s phrase table, so the same call reads checked 25 September 2026 here and ২৫ সেপ্টেম্বর ২০২৬ তারিখে যাচাই on a
Bengali page — and the machine-readable form goes in the datetime attribute, where a reader’s tooling looks. A
date the engine cannot read renders the call’s own literal, the way any call does.
:abbr is the whole of what an engine feature used to do (ADR-0137), and it is one line of template. What the
deleted code added on top was marking every occurrence in a document from a single definition — which no call can
do, because a call marks the one place it is written.
An icon is a call like any other — — since ADR-0138 retired the :name: spelling and the 96 lines
whose main job was refusing to match 10:30:15, a ratio of 4:3 or a sentence beginning “Note:”. khata answers with
Lucide’s drawing of that name, inlined in the text’s own colour and height —
— and :i is :icon for short. A brand’s mark is under brand/:
, and a way to be paid, for a sponsor page:
. An emoji by its GitHub name is the character itself, 🎉
✨. And a chord is Ctrl+C, or Ctrl+C for short. A name no fragment defines writes itself back rather than vanishing: :nosuch[this text survives].
Structures for technical writing
A procedure, where the numbering stays the browser’s and the source stays copy-pasteable:
:::steps{title="Serving your own site"}
1. Put a Markdown file in `publications/posts/`.
2. Run `khosra -site .` and open the address it prints.
3. Add `templates/theme.css` when the reference styling stops fitting.
:::
Serving your own site
- Put a Markdown file in
publications/posts/. - Run
khosra -site .and open the address it prints. - Add
templates/theme.csswhen the reference styling stops fitting.
A row of cards or figures is :::columns, further up: one block a column, as many as fit.
Media, and the other half of the same discovery
A leaf call’s name is as open as a container’s — ::name{k=v} on its own line renders through a fragment of
that name, so ::video and ::audio are two templates and no engine change either. They began in this zoo and
now ship in the production theme, so what renders here is khata’s, not a copy kept beside it.
::video{src=rain.webm poster=poster.svg track=rain.vtt caption="Two seconds of nothing, 1.7 KB of it" loop=yes}
track= is a WebVTT file of captions, in the language of the page around it; the player’s captions control
turns it on. A recording takes no track — a browser paints captions only into a video’s picture — so its
accessible form is a transcript, which is prose, under it:
::audio{src=gauge.ogg caption="A 220 Hz tone, standing in for a [field recording](https://en.wikipedia.org/wiki/Field_recording)"}
:::details{summary=Transcript}
A steady tone at 220 Hz, for two seconds. No words.
:::
Transcript
A steady tone at 220 Hz, for two seconds. No words.
Somebody else’s page, playable here, is ::embed — and it asks nothing of them until it is clicked. Write the
page’s own address, the one in the address bar; the engine asks that page, out of band, what its player is, and
copies its picture to this site for the poster. What shows first is that poster, inside a frame whose document is
this page’s; the click is what sends the frame to the host the label names. No script, on either side, so a reader
with JavaScript off gets the same promise. Until the page has answered — the first moments after a page is
published — the call is a plain link.
::embed{src=https://www.youtube.com/watch?v=aqz-KE-bpKQ caption="Blender Foundation, 2008"}
A YouTube player is sent to youtube-nocookie.com, the same player without the cookie. A gist offers no such
answer, but its code alone is a page made to be framed, so a gist’s address is enough too — and it gets a taller box,
being a document rather than a film:
::embed{src=https://gist.github.com/octocat/6cad326836d38bd3a7ae caption="The smallest gist there is"}
Or quote the gist rather than frame it. A fence whose file= is the gist’s raw address is fetched in the
background, kept, and coloured here like any code of yours: nothing of GitHub’s runs, and the reader never asks it
for anything. expires= says how old the copy may get before it is fetched again, and source= names the page to
credit under it — the gist’s own, where the address read from is its raw file.
```ruby file=https://gist.githubusercontent.com/octocat/6cad326836d38bd3a7ae/raw/hello_world.rb title="hello_world.rb" expires=24h source=https://gist.github.com/octocat/6cad326836d38bd3a7ae
```
A page that names no player — a map’s export page — is the player itself, and then the poster is yours:
::embed{src=https://www.openstreetmap.org/export/embed.html?bbox=88.0%2C21.5%2C92.7%2C24.5&layer=mapnik poster=delta.svg alt="A drawing of the delta's rivers meeting the sea" title="Map of the Bengal delta" caption="OpenStreetMap, loaded only when asked"}
When the page is worth pointing at rather than playing, ::oembed is its card: the picture, the title, what it
says about itself, who made it and where, and a link out. No frame and nothing of theirs runs; the picture is this
site’s copy.
::oembed{src=https://soundcloud.com/forss/flickermood}
A page that offers no oEmbed still makes a card, from what it says of itself — its OpenGraph, its title, its first paragraph, its site’s name and icon (khosra ADR-0585):
::oembed{src=https://en.wikipedia.org/wiki/Rain_gauge}
src, poster and track on a film or a recording are written relative to the publication and need no resolving: a publication’s own
files are served under its URL, so rain.vtt sitting beside this file is /pages/blocks/rain.vtt. What the
engine does not do is transcode — there is no derivative pass for video, and a poster is a picture you made
yourself. Nothing plays until it is asked to, and loop comes muted.
Classes and ids, without a block at all
Sometimes there is no block — there is a paragraph that should look different, or three words that should. {#id .class} attaches one, in several positions and one grammar (ADR-0140), and the grammar is goldmark’s own: it is the
same parser that has always read ## A heading {#anchor}.
The opening words, set larger than the rest.
{.lede}
A [run of words]{.whisper} inside an ordinary sentence.
:::div{.callout #day-three}
A region of several blocks.
:::
The opening words, set larger than the rest.
A run of words inside an ordinary sentence, said under the breath, and the region below is a div — the one fragment the
reference theme carries for this, because reaching a run of blocks is a contract-level need rather than taste.
Two paragraphs, one class, one id.
The #/. shorthand is read by the same argument parser every call uses, beside a call’s own switches:
:::gallery{plate .mine} is a gallery as wide as a plate, carrying a class of yours.
A fence takes them after its language, where a fence keeps its options — here the same .callout, on a table of
readings:
gauge 14 mm
tin 12 mm
Only id and class get through. [a span]{onclick=alert(1)} is not an attribute group, so it stays on the page
as the text you are reading now — braces and all — rather than becoming a span with the attribute quietly dropped.
The engine writes no rule about onclick to achieve that: goldmark’s GlobalAttributeFilter is the allowlist, and
the parser refuses anything that is not one of the two.
A heading takes its anchor in its own braces, and khosra check will tell you if you also put one on the line
below — the line below wins, and an anchor that stops answering is a link somebody else already sent.
Which pictures a block shows
A gallery’s body is the answer (ADR-0253). You write the pictures you mean, in the order you mean them, in Markdown’s own image syntax — and the name in front only decides which fragment lays them out.
:::gallery



:::
A picture’s own words work on the whole gallery. {fixed} keeps every picture from opening larger when pressed —
swatches are furniture, not photographs:
:::gallery{fixed}



:::
Four pictures sit beside this page and three are in each gallery: poster.svg is the diagram further up, not a
swatch. A glob answered this until ADR-0253 — src=swatch-*.svg — and the reason it stopped is the reason it was
never quite safe: the next file dropped in this directory joins the set silently, and a page that changes because
of a filename is a page nobody edited.
Order, words and selection are all one thing now, and it is the thing you can see. There is no frontmatter list to keep in step, no filename convention deciding sequence behind your back, and nothing to explain when the two disagree — which they did, and this page used to have three paragraphs about it.
The same three lines with a different name in front of them is a different layout and no engine change:
:::contactsheet for a proof sheet, say. Define the fragment, and that is the whole of it.
Things that need no block at all
The site root is trusted, so raw HTML renders (ADR-0060), and some things want a line of CSS rather than a name:
Press Ctrl + K to search. That is two <kbd> elements and one CSS rule.
A note to yourself is the one thing raw HTML gets wrong: an HTML comment is raw HTML, so it is published
verbatim like everything else, and khosra check warns about every one it finds. The form that renders nothing
is a link definition nobody links to — there is one on the line above this paragraph in the source of this page,
and it is not in the page you are reading.
[//]: # (a note only the author sees)
Already in the engine, shown elsewhere
Footnotes1, tables, definition lists, task lists, ~sub~ and ^sup^ and marks and strike,
icons, pictures with a srcset, and ::include — each demonstrated on the page that uses it for
real rather than piled up here. A contents list is no longer among them: khata offers one to any page with
more than one heading, so there is no call to demonstrate (khosra ADR-0264).
A language khosra was taught here
Chroma ships lexers for a few hundred languages and none of them is this. syntax/dialogue.xml in this site’s
root defines one — speaker names, stage directions, and the rest as plain text — and khosra registers it before
it renders anything, so a fence may name it like any built-in (khosra ADR-0268).
ANNOUNCER: The engine ships no lexer for this.
[a pause, for effect]
AUTHOR: Then the site brings one.
— and that is the whole feature
A theme may ship lexers too, for languages it has taken the trouble to colour. Where both provide the same
name the site wins, so a site can correct a theme’s lexer without editing the theme. A file chroma cannot
parse is skipped with a warning and its fence renders as plain text: a half-written lexer costs a page its
colour and nothing else. khosra check names such a fence at its line, and a misspelt language too, asking the
same lexers a rebuild loads (khosra ADR-0415) — which is why the dialogue fence above passes it.
-
Which are the engine’s, namespaced per included file so two fragments cannot collide. ↩︎
সাবস্ক্রাইব
মাপ ওঠে যখন মাপা হয়, কোনো নিয়মে নয়: বেশিরভাগ সপ্তাহে দুবার, বর্ষায় রোজ। যেভাবেই অনুসরণ করুন, আপনার কিছুই এখানে রাখা হয় না।
- ফিড রিডারে
- Atom · JSON Feed. প্রতিটি বিভাগের আলাদা ফিডও আছে: বিভাগের ঠিকানার শেষে feed.xml।
- ফেডিভার্সে
- ম্যাস্টোডন বা অন্য যেকোনো ফেডিভার্স অ্যাপে https://adventure.x.bdeshi.space/ খুঁজে ফলো করুন।
- নিজের সাইট থেকে
- ইন্ডিওয়েব রিডারে https://adventure.x.bdeshi.space/bn/ ফলো করুন। নিজের সাইট থেকে কোনো লেখার উত্তর, লাইক বা রিপোস্ট ওয়েবমেনশনে এখানকার লেখায় পৌঁছায়।
A Zoo of Article Blocks
Each block below shows its source and then itself. None of them needed an engine change: :::name{k=v}
accepts any name and renders through a theme fragment of that name, so a block library is a file of templates
plus a stylesheet. Every one below is khata’s now, which draws them on every site — verse, the epigraph, the dated
notice, :abbr, the highlights — so a theme of your own copies the define and the partial it wants. The classes an
author writes, at the foot, are styled by this page alone, through styles: in its frontmatter.
The reference theme deliberately carries none of this — it demonstrates the contract, not a design.
Verse
Poetry needs its line breaks kept, and its indents.
:::verse{by="nobody in particular"}
The rain came down in sheets,
then stopped, as if embarrassed.
Three lines. Three breaks.
:::
The rain came down in sheets, then stopped, as if embarrassed. Three lines. Three breaks.
goldmark keeps the newline inside the paragraph, but not the indent a line began with: khosra puts that back for
every container’s lines (ADR-9015), and khata’s white-space: pre-wrap shows both. No trailing double spaces, no
<br> in the source.
Pull quote
This one graduated: khata carries pullquote itself now, hung half out of the column beside running prose —
In the Margins shows it where it belongs. Here it has no prose to hang beside, so it is
{centred} across the column instead (Where a Block Sits has the other places).
:::pullquote{centred by="The paragraph above"}
A sentence worth setting apart at display size.
:::
A sentence worth setting apart at display size.
Epigraph
:::epigraph{by="Borges, probably"}
I have always imagined that Paradise will be a kind of library.
:::
I have always imagined that Paradise will be a kind of library.
Columns
Every top-level block of the body is one column, so the call carries no count and no separator. The block also widens past the measure — a column of code needs the room — and how many columns fit is CSS’s decision, not the author’s: below about 14rem a column stops being worth reading, so they stack rather than shrink.
Unlike the rest of this page, columns lives in the theme rather than in this site’s overlay. It is a block
the production theme carries, and the demo shows it rather than redefining it.
:::columns
Left. Ordinary Markdown, including **emphasis** and lists.
Right. Stacks under the left on a narrow screen, which is CSS's decision.
:::
Left. Ordinary Markdown, including emphasis and lists.
Right. Stacks under the left on a narrow screen, which is CSS’s decision.
Three blocks are three columns. A fourth wraps onto a second row rather than crushing the rest.
:::columns
**Fetch.** Pull the archive down from the settings page.
**Strip.** Drop the assignment so the file parses as JSON.
**Post.** Replay the ids against the endpoint.
:::
Fetch. Pull the archive down from the settings page.
Strip. Drop the assignment so the file parses as JSON.
Post. Replay the ids against the endpoint.
A column wanting several blocks wraps them in :::col, and the outer fence grows a colon so the inner ones
close first (ADR-0117). This is also how a column holds another call — a note, a figure, or a nested :::columns
that subdivides its own track.
:::::columns
::::col
### Before
The archive ships the tweets as an assignment.
:::callout{note}
One file per part, all of them the same shape.
:::
::::
::::col
### After
Strip the assignment and it is plain JSON.
::::
:::::
Before
The archive ships the tweets as an assignment.
Note
One file per part, all of them the same shape.
After
Strip the assignment and it is plain JSON.
A :::columns inside a column subdivides that column’s own track rather than reaching for the page again.
::::columns
Whole, on the left.
:::columns
Top right.
Bottom right.
:::
::::
Whole, on the left.
Top right.
Bottom right.
Callouts
One call for every box beside the text: callout, with two words in its braces — what it is and how it is
drawn, either or both, in any order. Nothing in the engine knows any of these words; each is the theme’s. Every kind
in every form, in English and Bengali: Callouts, Every Way.
What it is
The kind sets the mark, the colour and the word a box is headed by.
:::callout{note}
The gauge is read at nine every morning.
:::
Note
The gauge is read at nine every morning.
Tip
Read the meniscus at eye level, not from above.
Warning
A gauge under a tree reads low all season.
Next up
Calibrate the funnel against a measured litre.
Blocked on
Waiting on a replacement bottle; the old one cracked.
Known issues
The ruler’s first centimetre is worn off.
How it is drawn
The same warning in every form: the soft box (no word), window, tinted — with and without a title — run-in
and hanging.
:::callout{warn window}
A gauge under a tree reads low all season.
:::
:::callout{warn tinted}
A gauge under a tree reads low all season.
:::
:::callout{warn run-in title="Placement"}
A gauge under a tree reads low all season.
:::
Warning
A gauge under a tree reads low all season.
A gauge under a tree reads low all season.
Placement
A gauge under a tree reads low all season.
A gauge under a tree reads low all season, and a gauge beside a wall reads high when the wind drives the rain into it — the wall catches what the funnel would not.
Placement
A gauge under a tree reads low all season.
A gauge under a tree reads low all season.
A changelog
hanging and the four changelog kinds, a run of them close together; a date where one is given.
:::callout{added hanging on=2026-06-01}
A second gauge, on the roof's north edge.
:::
:::callout{fixed hanging}
June's figures: the first draft read millimetres as centimetres.
:::
A second gauge, on the roof’s north edge.
Readings move from nine to eight in the morning.
June’s figures: the first draft read millimetres as centimetres.
The old plastic funnel, cracked by the sun.
Chips
Inline, a word or two in a kind’s colour and mark: the new gauge is beta, the reading confirmed, the old funnel gone, and a plain one draft.
the new gauge is :callout[beta]{warn}, … a plain one :callout[draft]
A dated notice
:::callout{on=2026-04-02}
Corrected the gauge figures: the first draft read millimetres as centimetres.
:::
Corrected the gauge figures: the first draft read millimetres as centimetres.
A number worth its own line
One of khata’s highlights; Highlights shows them all.
:::stat{label="millimetres, June to September"}
2,431
:::
2,431
Timeline
A description list with a rule down its side, so a screen reader hears terms and descriptions rather than a
decorated div. khata carries timeline itself now, with a second, long form — see
A Decade of Gauges.
:::timeline
2024
: The first gauge, bought secondhand.
2025
: Three more, and a notebook.
2026
: This site.
:::
- 2024
- The first gauge, bought secondhand.
- 2025
- Three more, and a notebook.
- 2026
- This site.
What a callout actually holds
A callout’s body is a block — paragraphs, lists, code, figures, and other calls. The fence is longer on the outside so the inner one closes first (ADR-0117).
::::callout{warn title="Before you run this"}
It rewrites files in place. Two things to check first:
1. The gauge log is committed.
2. You are not in `/`.
:::callout{tip}
`--dry-run` prints what it would do and touches nothing.
:::

::::
Before you run this
It rewrites files in place. Two things to check first:
- The gauge log is committed.
- You are not in
/.
Tip
--dry-run prints what it would do and touches nothing.
A callout is a container like any other, so nothing above is a special case: the list, the nested tip and the figure are the same mechanisms that work anywhere else.
Folded sections, with no JavaScript
details is already in the reference theme, and group= makes several mutually exclusive through the native
name attribute: opening one closes the others, an accordion. Tabs, picked from a row of titles, are ::::tabs.
:::details{summary="Show the workings" group="one"}
Grouped panels close each other. No script involved.
:::
Show the workings
Grouped panels close each other. No script involved.
Or these workings
Because name is the browser’s own mechanism for exclusivity.
Code, which the engine already frames
A title, line numbers, a starting offset and highlighted lines are all engine options — code.go reads them and
the theme frames the result.
```go {title="rank.go" numbers=1 hl="2-3"}
func score(b content.Publication, terms []string) int {
title, body := tally(tokens(b.Title)), tally(tokens(string(b.Body)))
total := 0
return total
}
```
1func score(b content.Publication, terms []string) int {
2 title, body := tally(tokens(b.Title)), tally(tokens(string(b.Body)))
3 total := 0
4 return total
5}
Code inside a sentence names its language the way a fence does, with the word in braces straight after it — so
`tally(tokens(b.Title))`{go} reads as tally(tokens(b.Title)), in the fence’s colours and the sentence’s
size (khosra ADR-0480). A word no lexer knows leaves the span plain and the braces showing, and khosra check names
it.
Structures for prose
A scene break needs no block: khata draws a line of three dashes between two paragraphs as one, an asterism in a wider gap rather than a rule across the column:
The gauge was left to itself for the night.
---
By morning the roof was a lake.
The gauge was left to itself for the night.
By morning the roof was a lake.
Dialogue is khata’s :::chat — a line to each turn, set as a definition list, so a screen reader hears speaker and
speech rather than a decorated box. With no options it is a transcript, names in a column as a play’s script sets them; bubbles makes it
a messaging thread (In the Margins uses it):
:::chat{cast="r=Ruma a=Abbas"}
r: You measured it wrong.
a: I measured it twice.
:::
Ruma: You measured it wrong.
Abbas: I measured it twice.
A letter, on ruled paper, with whatever of place, date, to and from you give it — to is the greeting as
you would write it, and takes its comma:
:::letter{place=Kalabagan date=2026-08-12 to="Dear Ruma" from=A.}
The gauge is yours if you want it. I have stopped writing the numbers down.
The funnel is on the shelf by the stairs, still level.
:::
Kalabagan,
Dear Ruma,
The gauge is yours if you want it. I have stopped writing the numbers down.
The funnel is on the shelf by the stairs, still level.
A.
An email, as a mail client opens one — subject, from, to, cc and date, each only if you give it:
:::email{subject="Re: the gauge" from="Ruma <ruma@example.com>" to=A. date=2026-08-14}
Took it. It reads 2 mm already, and it has not rained.
Is it meant to do that?
:::
Re: the gauge
- From
- Ruma <ruma@example.com>
- To
- A.
- Sent
- Subject
- Re: the gauge
Took it. It reads 2 mm already, and it has not rained.
Is it meant to do that?
And the mark a printed essay closes with, which needs no call any more: khata sets one at the end of every titled piece’s last line by itself — this page’s included.
Two languages side by side
This is what nesting was worth fixing for. The outer fence is longer, so each :::col is a container of its
own instead of the end of the outer one — and a container that closes early used to delete its inner text. khata’s
:::columns lays them out, and lang= on a :::col says which language the column is in.
:::::columns
::::col{lang=en}
:::verse
The rain came down in sheets,
then stopped, as if embarrassed.
:::
::::
::::col{lang=bn}
:::verse
বৃষ্টি চাদরের মতো নেমে এল,
তারপর থেমে গেল, যেন লজ্জা পেয়ে।
:::
::::
:::::
The rain came down in sheets, then stopped, as if embarrassed.
বৃষ্টি চাদরের মতো নেমে এল, তারপর থেমে গেল, যেন লজ্জা পেয়ে।
Three levels, and each one is doing work: columns lays them out, col carries the lang, and verse keeps the
line breaks — which a poem needs and a prose column must not have. Five colons on the outside, three on the inside,
one per level of depth.
The lang attribute is not decoration: it is what a screen reader switches voice on and what the browser picks a
font and hyphenation dictionary from. Written by hand it would be raw HTML on every stanza.
Inline marks
:name[text]{args} is the third form of the same syntax — inside a sentence rather than on a line. The reference
theme ships several — lang, because a bilingual page is mixed sentence by sentence, and kbd, icon, meta,
human-made and checked beside it.
The word for water is :lang[জল]{tag=bn} there.
Press :kbd[Ctrl] then :kbd[K].
Text is stored in :abbr[NFC]{title="Normalization Form C"}.
The word for water is জল there. Press Ctrl then K. Text is stored in NFC.
A claim with a shelf life can carry its own date, which is the reference theme’s checked (ADR-0364):
The default derivation is Argon2id :checked[2026-09-25].
The default derivation is Argon2id .
The brackets hold the date and nothing else. The word around it, the numerals and the word order come from the
engine’s phrase table, so the same call reads checked 25 September 2026 here and ২৫ সেপ্টেম্বর ২০২৬ তারিখে যাচাই on a
Bengali page — and the machine-readable form goes in the datetime attribute, where a reader’s tooling looks. A
date the engine cannot read renders the call’s own literal, the way any call does.
:abbr is the whole of what an engine feature used to do (ADR-0137), and it is one line of template. What the
deleted code added on top was marking every occurrence in a document from a single definition — which no call can
do, because a call marks the one place it is written.
An icon is a call like any other — — since ADR-0138 retired the :name: spelling and the 96 lines
whose main job was refusing to match 10:30:15, a ratio of 4:3 or a sentence beginning “Note:”. khata answers with
Lucide’s drawing of that name, inlined in the text’s own colour and height —
— and :i is :icon for short. A brand’s mark is under brand/:
, and a way to be paid, for a sponsor page:
. An emoji by its GitHub name is the character itself, 🎉
✨. And a chord is Ctrl+C, or Ctrl+C for short. A name no fragment defines writes itself back rather than vanishing: :nosuch[this text survives].
Structures for technical writing
A procedure, where the numbering stays the browser’s and the source stays copy-pasteable:
:::steps{title="Serving your own site"}
1. Put a Markdown file in `publications/posts/`.
2. Run `khosra -site .` and open the address it prints.
3. Add `templates/theme.css` when the reference styling stops fitting.
:::
Serving your own site
- Put a Markdown file in
publications/posts/. - Run
khosra -site .and open the address it prints. - Add
templates/theme.csswhen the reference styling stops fitting.
A row of cards or figures is :::columns, further up: one block a column, as many as fit.
Media, and the other half of the same discovery
A leaf call’s name is as open as a container’s — ::name{k=v} on its own line renders through a fragment of
that name, so ::video and ::audio are two templates and no engine change either. They began in this zoo and
now ship in the production theme, so what renders here is khata’s, not a copy kept beside it.
::video{src=rain.webm poster=poster.svg track=rain.vtt caption="Two seconds of nothing, 1.7 KB of it" loop=yes}
track= is a WebVTT file of captions, in the language of the page around it; the player’s captions control
turns it on. A recording takes no track — a browser paints captions only into a video’s picture — so its
accessible form is a transcript, which is prose, under it:
::audio{src=gauge.ogg caption="A 220 Hz tone, standing in for a [field recording](https://en.wikipedia.org/wiki/Field_recording)"}
:::details{summary=Transcript}
A steady tone at 220 Hz, for two seconds. No words.
:::
Transcript
A steady tone at 220 Hz, for two seconds. No words.
Somebody else’s page, playable here, is ::embed — and it asks nothing of them until it is clicked. Write the
page’s own address, the one in the address bar; the engine asks that page, out of band, what its player is, and
copies its picture to this site for the poster. What shows first is that poster, inside a frame whose document is
this page’s; the click is what sends the frame to the host the label names. No script, on either side, so a reader
with JavaScript off gets the same promise. Until the page has answered — the first moments after a page is
published — the call is a plain link.
::embed{src=https://www.youtube.com/watch?v=aqz-KE-bpKQ caption="Blender Foundation, 2008"}
A YouTube player is sent to youtube-nocookie.com, the same player without the cookie. A gist offers no such
answer, but its code alone is a page made to be framed, so a gist’s address is enough too — and it gets a taller box,
being a document rather than a film:
::embed{src=https://gist.github.com/octocat/6cad326836d38bd3a7ae caption="The smallest gist there is"}
Or quote the gist rather than frame it. A fence whose file= is the gist’s raw address is fetched in the
background, kept, and coloured here like any code of yours: nothing of GitHub’s runs, and the reader never asks it
for anything. expires= says how old the copy may get before it is fetched again, and source= names the page to
credit under it — the gist’s own, where the address read from is its raw file.
```ruby file=https://gist.githubusercontent.com/octocat/6cad326836d38bd3a7ae/raw/hello_world.rb title="hello_world.rb" expires=24h source=https://gist.github.com/octocat/6cad326836d38bd3a7ae
```
A page that names no player — a map’s export page — is the player itself, and then the poster is yours:
::embed{src=https://www.openstreetmap.org/export/embed.html?bbox=88.0%2C21.5%2C92.7%2C24.5&layer=mapnik poster=delta.svg alt="A drawing of the delta's rivers meeting the sea" title="Map of the Bengal delta" caption="OpenStreetMap, loaded only when asked"}
When the page is worth pointing at rather than playing, ::oembed is its card: the picture, the title, what it
says about itself, who made it and where, and a link out. No frame and nothing of theirs runs; the picture is this
site’s copy.
::oembed{src=https://soundcloud.com/forss/flickermood}
A page that offers no oEmbed still makes a card, from what it says of itself — its OpenGraph, its title, its first paragraph, its site’s name and icon (khosra ADR-0585):
::oembed{src=https://en.wikipedia.org/wiki/Rain_gauge}
src, poster and track on a film or a recording are written relative to the publication and need no resolving: a publication’s own
files are served under its URL, so rain.vtt sitting beside this file is /pages/blocks/rain.vtt. What the
engine does not do is transcode — there is no derivative pass for video, and a poster is a picture you made
yourself. Nothing plays until it is asked to, and loop comes muted.
Classes and ids, without a block at all
Sometimes there is no block — there is a paragraph that should look different, or three words that should. {#id .class} attaches one, in several positions and one grammar (ADR-0140), and the grammar is goldmark’s own: it is the
same parser that has always read ## A heading {#anchor}.
The opening words, set larger than the rest.
{.lede}
A [run of words]{.whisper} inside an ordinary sentence.
:::div{.callout #day-three}
A region of several blocks.
:::
The opening words, set larger than the rest.
A run of words inside an ordinary sentence, said under the breath, and the region below is a div — the one fragment the
reference theme carries for this, because reaching a run of blocks is a contract-level need rather than taste.
Two paragraphs, one class, one id.
The #/. shorthand is read by the same argument parser every call uses, beside a call’s own switches:
:::gallery{plate .mine} is a gallery as wide as a plate, carrying a class of yours.
A fence takes them after its language, where a fence keeps its options — here the same .callout, on a table of
readings:
gauge 14 mm
tin 12 mm
Only id and class get through. [a span]{onclick=alert(1)} is not an attribute group, so it stays on the page
as the text you are reading now — braces and all — rather than becoming a span with the attribute quietly dropped.
The engine writes no rule about onclick to achieve that: goldmark’s GlobalAttributeFilter is the allowlist, and
the parser refuses anything that is not one of the two.
A heading takes its anchor in its own braces, and khosra check will tell you if you also put one on the line
below — the line below wins, and an anchor that stops answering is a link somebody else already sent.
Which pictures a block shows
A gallery’s body is the answer (ADR-0253). You write the pictures you mean, in the order you mean them, in Markdown’s own image syntax — and the name in front only decides which fragment lays them out.
:::gallery



:::
A picture’s own words work on the whole gallery. {fixed} keeps every picture from opening larger when pressed —
swatches are furniture, not photographs:
:::gallery{fixed}



:::
Four pictures sit beside this page and three are in each gallery: poster.svg is the diagram further up, not a
swatch. A glob answered this until ADR-0253 — src=swatch-*.svg — and the reason it stopped is the reason it was
never quite safe: the next file dropped in this directory joins the set silently, and a page that changes because
of a filename is a page nobody edited.
Order, words and selection are all one thing now, and it is the thing you can see. There is no frontmatter list to keep in step, no filename convention deciding sequence behind your back, and nothing to explain when the two disagree — which they did, and this page used to have three paragraphs about it.
The same three lines with a different name in front of them is a different layout and no engine change:
:::contactsheet for a proof sheet, say. Define the fragment, and that is the whole of it.
Things that need no block at all
The site root is trusted, so raw HTML renders (ADR-0060), and some things want a line of CSS rather than a name:
Press Ctrl + K to search. That is two <kbd> elements and one CSS rule.
A note to yourself is the one thing raw HTML gets wrong: an HTML comment is raw HTML, so it is published
verbatim like everything else, and khosra check warns about every one it finds. The form that renders nothing
is a link definition nobody links to — there is one on the line above this paragraph in the source of this page,
and it is not in the page you are reading.
[//]: # (a note only the author sees)
Already in the engine, shown elsewhere
Footnotes1, tables, definition lists, task lists, ~sub~ and ^sup^ and marks and strike,
icons, pictures with a srcset, and ::include — each demonstrated on the page that uses it for
real rather than piled up here. A contents list is no longer among them: khata offers one to any page with
more than one heading, so there is no call to demonstrate (khosra ADR-0264).
A language khosra was taught here
Chroma ships lexers for a few hundred languages and none of them is this. syntax/dialogue.xml in this site’s
root defines one — speaker names, stage directions, and the rest as plain text — and khosra registers it before
it renders anything, so a fence may name it like any built-in (khosra ADR-0268).
ANNOUNCER: The engine ships no lexer for this.
[a pause, for effect]
AUTHOR: Then the site brings one.
— and that is the whole feature
A theme may ship lexers too, for languages it has taken the trouble to colour. Where both provide the same
name the site wins, so a site can correct a theme’s lexer without editing the theme. A file chroma cannot
parse is skipped with a warning and its fence renders as plain text: a half-written lexer costs a page its
colour and nothing else. khosra check names such a fence at its line, and a misspelt language too, asking the
same lexers a rebuild loads (khosra ADR-0415) — which is why the dialogue fence above passes it.
-
Which are the engine’s, namespaced per included file so two fragments cannot collide. ↩︎
মাপ ওঠে যখন মাপা হয়, কোনো নিয়মে নয়: বেশিরভাগ সপ্তাহে দুবার, বর্ষায় রোজ। যেভাবেই অনুসরণ করুন, আপনার কিছুই এখানে রাখা হয় না।
- ফিড রিডারে
- Atom · JSON Feed. প্রতিটি বিভাগের আলাদা ফিডও আছে: বিভাগের ঠিকানার শেষে feed.xml।
- ফেডিভার্সে
- ম্যাস্টোডন বা অন্য যেকোনো ফেডিভার্স অ্যাপে https://adventure.x.bdeshi.space/ খুঁজে ফলো করুন।
- নিজের সাইট থেকে
- ইন্ডিওয়েব রিডারে https://adventure.x.bdeshi.space/bn/ ফলো করুন। নিজের সাইট থেকে কোনো লেখার উত্তর, লাইক বা রিপোস্ট ওয়েবমেনশনে এখানকার লেখায় পৌঁছায়।