Tip
One import renders every block on this site.
Install
Section titled "Install"pnpmpnpm add comark @comark/html @onmax/comarknpmnpm install comark @comark/html @onmax/comarkRender
Section titled "Render"Pass
onmax()to the renderer.
The deploy waits while more than 12 pigeons sit on the roof.
Pineapple pizza needs two thirds of the Friday vote.
:include{src="./partials/install.md" code}
---
note: The frontmatter of a partial is dropped.
---
Install the plugin with Comark, ideally before standup:
```sh
pnpm add comark comark-include
```这句话是粗体。下一句不是。
이 문장은 굵게.다음 문장은 아닙니다.
Pond census tests1 passed1 failed1 skipped4.2 s
pond.test.ts › counts the geese
expected 3 to be 4
AssertionError: expected 3 to be 4
at pond.test.ts:12:20Moving the pigeon map to a worker cut the main bundle 412 kB → 388 kB ↓ 5.8% and the time to first sighting 2.4 s → 1.9 s ↓ 20.8% on a mid-range phone
-
Open the filters.
Before: the toolbar wraps -
Narrow the window.
After: one row at any width
packages
steps
+src
- +index.tsthe parse plugin
- ~package.json
- -legacy.tsfolded into index.ts
optionsobjectWhat the plugin takes.
iconResolverIconsResolves icons, from
createIcons() in comark-icon.downloadbooleanDefault: trueInlines each image while parsing.
options
level: the heading level that starts each step.start: the number of the first step.
:include{src="./partials/ducks.ts" region="estimate"}
const bugs = Math.round(ducks * 0.94);
return bugs;Failing
upload.test.ts times out on files over 10 MB.Passing
Every other test passes.- Background#fafaf9
- Foreground#1c1917
- Primaryoklch(0.55 0.2 264)
- Danger#dc2626
- Overlayrgb(0 0 0 / 40%)
titlestringrequiredThe text above the card's content.
colorstringDefault: primaryTints the icon and the hovered border.
Press ⌘ K to search. Water is H2O.
Where did the script go?
The source has a<script> after this sentence. GitHub drops it, and so does html().
- Status
- Ready for review
- Author
- onmax
- Tags
- mapperformance
The pigeon map counts each plaza in a worker, so the page scrolls while it counts.
| Metric | Before | After | Change |
|---|---|---|---|
| JavaScript | 412 kB | 388 kB | ↓ 5.8% |
| Largest paint | 2.4 s | 1.9 s | ↓ 20.8% |
Pigeon map tests3 passed1.8 s
The worker starts on loadon the first scrollMost visitors never scroll the map.
| Mallard | 14 | North |
| Pigeon | 212 | Plaza |
| Heron | 2 | North |
ABCA
Bugs fixed fell with the duck supply.
B
r now counts the office cat.
C
The pigeons ate week 15.
v4.0.0
The deploy waits when more than twelvefifteen pigeons sit on the roof.
Count them afterbefore the stand-up, from the east windowThe west one faces the parking lot..
Pizza is on FridayPineapple still needs a vote..
Rollout plan
Section titled "Rollout plan"Point at the step people ask about, not the top of the page.
Week one
Section titled "Week one"Internal teams only.
Press Ctrl + Shift + K to open the pigeon counter, and Esc to close it.
On a Mac, it's Cmd + Option + K. Page through the log with Page Up and Page Down.
Pizza is ordered on Fridays[1].
Footnotes
Section titled "Footnotes"-
Pineapple needs a vote, and the vote needs two thirds.
The order goes in at noon:
- one margherita per four people
- one diavola for the table
pnpm exec spurious correlate --x "rubber ducks bought" --y "bugs fixed" --office berlin --moon-phase waxing --min-r 0.9 > ducks.csv| Metric | Before | After | Change |
|---|---|---|---|
| JavaScript | 412 kB | 388 kB | ↓ 5.8% |
| Largest paint | 2.4 s | 1.9 s | ↓ 20.8% |
| Requests | 38 | 41 | ↑ 7.9% |
この文は太字。次の文は普通です。
会議は「金曜日」に移りました。
鳩の数を数える。もう数えません。
Loft redesign
- Status
- Draft
- Author
- onmax
The loft moves to the roof in spring.
Before
1After
2Before
- 1Apply sits 6px lower than the chips.
After
- 2Apply lines up with the chips.
| function close() { | ||
| dialog.close(); | ||
| history.back(); | ||
| if (opened) history.back(); | ||
| } |
123456- 1
boxframes an element. - 2
circlerings a small detail. - 3
underlinemarks text. - 4
highlightwashes over an area. - 5
crossstrikes something out. - 6
checkapproves and sits beside its target.
import { defineConfig } from "vite";
6 collapsed lines
import vue from "@vitejs/plugin-vue";
import icons from "unplugin-icons/vite";
import components from "unplugin-vue-components/vite";
import inspect from "vite-plugin-inspect";
import checker from "vite-plugin-checker";
import { comark } from "./comark";
export default defineConfig({
plugins: [comark(), vue()],
});
The button moves from #3b82f6 to oklch(0.55 0.2 264), and its hover from rgb(37 99 235) to hsl(226 71% 40%).
Built with Vue and Vite, deployed to Cloudflare.
posva maintains 
Vue Router, and 
danielroe leads 
Nuxt. 
Evan posts on Bluesky.
Note
Drafts save every few seconds, so closing the tab keeps your work.
Tip
Press ⌘K to search every document.
Important
Releases ship from main only.
Warning
Changing the slug breaks links people already shared.
Caution
Deleting a folder deletes every document in it.
function close() {
dialog.close();
history.back();
if (opened) history.back();
}
Magnetoreception in homing pigeons
How do homing pigeons navigate?Pigeon map tests3 passed1.8 s
webpack
Vite
Nuxt docsHold Shift and press Duck Button to page the rubber duck.
Deploy with Ctrl + Alt + 🍕 on Fridays only.
1
- 1The playground opens the editor right away, so it stays slow.
pnpm add comark @comark/html comark-codepnpm
pnpm add comark-tabsnpm
npm install comark-tabsyarn
yarn add comark-tabs- Status
- Ready for review
- Author
- onmax
- Date
- 2026-10-23
- Tags
- colorsdocs
The palette page now shows every token of the pigeon tracker's theme.
docs
- index.md
src
- __init__.py
- pyproject.toml
| Benchmark | Before (ms) | After (ms) |
|---|---|---|
| Parse the duck census | 1,204 | 980 |
| Render the pond map | 88 | 91 |
| Count the pigeons | 412 | 388 |
Merge the pull request once its checks pass.
| export const MAX_FILTERS = 3; |
:include{src="./partials/ducks.ts" lines="8:10"}
export function ducksNeeded(bugs: number) {
return Math.ceil(bugs / 0.94);
}- Pigeon count
-
The number of pigeons on the office roof at 9:00.
Above 12, the deploy waits. Below 12, it ships.
- Count once, from the window.
- Pigeons that fly off mid-count still count.
- Pizza vote
- Fridays at noon. Pineapple needs two thirds.
1 / 2
Duck tests moved to Vitest: Migrated85%
Thanks 
onmax: this fixes #51, and onmax/comark-ui#73 builds on it.
1 / 3
and , as Nuxt UI writes it, draw the same icon.
ABC1A
Bugs fixed fall for the first time this quarter. So do the ducks.
B
r now counts the office cat.
C
Week 15 is missing for the pigeons.
- 1Apply waits until every filter is set, moon phase included.
$ pnpm build Bundling [==========] done dist/pigeons.js 12.4 kB dist/style.css 3.1 kB ✓ built in 412ms
- JavaScript
- 388 kB
- ↓ 5.8%
- Largest paint
- 1.9 s
- ↓ 20.8%
- Requests
- 41
- ↑ 7.9%
1. Find the export
1- 1Export CSV sits in the page header.
2. Set the filters
1- 1Open +2 filters and set the moon phase. The export includes only the rows the filters show.
3. Apply
1- 1Apply updates the table, and the export follows it.
1 / 3
function close() {
dialog.close();
history.back();
if (opened) history.back();
}Before
One long page of options.
After
Each option under its own heading.
Open the preview on your phone:
The office roof holds about 103 pigeons, and the 1st count of the day is at 9:00.
1 / 3
Ring sizes
Section titled "Ring sizes"Decision
Keep the existing endpoint. Clients pin its response shape.
lint-comark review.mdreview.md:1:1 comark/unclosed-block
::screnshot opened on line 1 is never closed.review.md:1:1 comark/unknown-component::screnshot on line 1 is not a known component.✖ 2 problemsThe deploy waits when the roof holds more than 12 pigeons[1], unless it's a hotfix[2].
Footnotes
Section titled "Footnotes"macOS
Press ⌘K to find the pigeon data.Windows
Press Ctrl+K to find the pigeon data.npm
npm install -D comark-tabspnpm
pnpm add -D comark-tabsyarn
yarn add --dev comark-tabsbun
bun add --dev comark-tabsThe flower opens once the page loads, as it did before the change:
ABCA
Bugs fixed fell with the duck supply.
B
r now counts the office cat.
C
The pigeons ate week 15.
- Flaky test
- A test that passes and fails on the same code.
- Rubber duck
- A listener who doesn't need to understand the bug.
- A bath toy.
RUN v3.2.4 /pigeon-tracker ✓ test/flock.test.ts (6 tests) ✓ test/routes.test.ts (4 tests) ✗ test/homing.test.ts (3 tests | 1 failed) Tests 1 failed | 12 passed
A promise callback never runs in the middle of other code. It waits in the microtask queue[1], and the browser empties that queue at a fixed point in each turn of the event loop.
A task runs
Section titled "A task runs"The current script, or one event handler, runs to its end.
Microtasks run
Section titled "Microtasks run"Every queued promise callback runs, and so do the ones they queue[1].
The page may paint
Section titled "The page may paint"Only now can the browser render, then take the next task[2].
Tip
A long chain of microtasks keeps the page from painting just like one long task does.
1.
Which line lets the browser paint before the rest of the work runs?
Show answer
await Promise.resolve()It queues a microtask, and microtasks all run before the page paints.
queueMicrotask(() => next())A microtask still runs before the browser takes its turn to paint.
Correct answer
await new Promise((r) => setTimeout(r))The timer's callback is a new task, so the page can paint before it.
Only a new task gives the browser a turn to paint. Microtasks, however many, run first.
2.
When does the browser run the microtask queue?
Show answer
After every task, before it renders or takes the next task
[1]
.
Sources
Using microtasks in JavaScriptdist/pigeons.js 12.4 kB dist/style.css 3.1 kB ✓ built in 412ms
Why does the build need Node 22?
node:sqlite caches the icons between builds, and it shipped in Node 22.5.src
components
- Button.vuethe one every page uses
- …
pages
- [slug].vue
- app.config.ts
- package.json
1A
A
Peak coffee.
- 1The new espresso machine arrives, and commits pass 700.
Anthony
Comark| Attempt | Wait |
|---|---|
| 1 | 1 s |
| 2 | 4 s |
| 3 | Until the pigeons leave |
Is it free?
Yes. Every package is MIT licensed.Does it need a script?
No. Each item is a native<details>, and type="single" gives them one name, so opening one closes the others.The alert sound the reviewer asked for:
The retro moved to Thursday[1], and the rubber duck[2] runs it.
Footnotes
Section titled "Footnotes"- Fork the repository and clone it.
- Run
pnpm install. - Open a pull request against
main.
What should the next lesson cover?
:include{src="./partials/install.md"}
Install the plugin with Comark, ideally before standup:
pnpm add comark comark-include1.
Which callback runs first once the current script ends?
Hint
Two queues are involved. Which one empties first?
Show answer
A
setTimeout(fn, 0) callbackA timer queues a task, which waits until the microtask queue is empty.
Correct answer
A resolved promise's
then callbackPromise callbacks are microtasks, and the microtask queue empties before the next task.
A
requestAnimationFrame callbackIt runs before the next paint, after the tasks already queued.
After every task, the event loop runs each queued microtask before it takes the next task, so a promise callback beats a zero-delay timer.
Decision
Moon phase and vibes collapse into +2 filters, so the toolbar stays on one row at 640px.
Before
1- 1Moon phase and vibes don't fit, so the toolbar wraps and pushes the table down.
After
2- 2Moon phase and vibes collapse into +2 filters.
1 / 2
| const visible = filters; | ||
| const visible = filters.slice(0, 3); | ||
| const hidden = filters.length - visible.length; |
| Width | Before | After |
|---|---|---|
| 640px | 105px | 56px |
| 1024px | 56px | 56px |
Read the incident report before the review, then come back to the checklist.
1.
Why does a promise callback run before a zero-delay timer?
Show answer
Promise callbacks are microtasks. The event loop empties the microtask queue after every task, before it takes the next one, and a timer's callback is a task.
| Check | Time | Result |
|---|---|---|
| Unit tests | 1.9 s | 412 passed |
| E2E | 48 s | 3 slow |
| Type check | 6.2 s | 2 errors |
Feeding schedule
Section titled "Feeding schedule"Homing routes
Section titled "Homing routes"Short flights
Section titled "Short flights"Long flights
Section titled "Long flights"Known pigeons
Section titled "Known pigeons"Before
12- 1Moon phase and vibes don't fit, so the toolbar wraps and pushes the table down.
- 2Apply sits 6px lower than the chips.
After
34- 3Moon phase and vibes collapse into +2 filters.
- 4Apply lines up with the chips.
1 / 2
Install the plugin
Section titled "Install the plugin"pnpm add comark-stepsRegister it
Section titled "Register it"Pass
steps()to the parser andcomponentsto the renderer.Write the steps
Section titled "Write the steps"Wrap the headings of a tutorial in
::steps.
A
A
Team goal: 45 min.
Breaking change in v2
render(markdown) is gone. Create a renderer once instead:
- pass it your
pluginsandcomponents - key
componentsby tag name
const render = createHtmlRenderer({ plugins, components });pnpm
pnpm add comark-tabsnpm
npm install comark-tabsyarn
yarn add comark-tabsAt 640px, moon phase and vibes push the filters onto a second row.
1- 1Apply sits 6px lower than the chips.
With moon phase and vibes behind +2 filters, everything fits on one row.
1- 1Apply lines up with the chips.
useAsyncData deprecated
Section titled "useAsyncData deprecated"
Use useFetch instead. v4 stable
- presetEvery plugin in one install
- annotateMarks and notes on screenshots
- castTerminal recordings as text
- chartsCharts from a Markdown table
- diagramsDiagrams drawn through Kroki
- mermaidMermaid diagrams drawn by Pele
- chipsLinks and @mentions as chips
- colorsSwatches for colors in code
- diffCompare two code fences
- embedVideos, audio, and live code
- mediaVideos and audio as images
- metricsDeltas, progress, stats, and tiles
- tableTables from CSV and JSON
- testsResults from a JUnit report
- githubGitHub's alerts, references, and HTML
- propertiesFrontmatter as a properties box
- sourcesCitations and a list of sources
- iconIconify icons in Markdown
- qrQR codes for preview links
- linksExternal links and heading anchors
- zoomZoom images and any block
- carouselSlides of any content
- tabsTabs and code groups
- codeCopy and wrap buttons on code
- detailsDetails and accordions
- file-treeFolders and files
- fieldsProps and options
- badgeBadges
- code-notesNumbered notes on code lines
- cardsCards and columns
- stepsNumbered steps
- quizQuestions, polls, and recall cards
- cjkEmphasis in Chinese, Japanese, and Korean
- figureImage captions from the title
- markHighlights and superscripts
- criticSuggested edits and comments
- deflistTerms and their definitions
- footnotesNumbered notes at the end of the page
- keysKeyboard shortcuts as kbd keys
- includePartials and snippets from files
- outlineA table of contents in the page
- xrefNumbered figures and references
- reading-timeWord count and reading time
- lintCatches what Comark forgives
Made for agents. Read by people.
Section titled "Made for agents. Read by people."Your agent writes the review in Markdown and your team reads the page. When a block is wrong, the plugins say how to fix it.
> [!TIP] Decision> Moon and Vibes move into **+2 filters**.> One row again. Fixes #51, as @onmax asked.::screenshot{src="/after.png" alt="Filter toolbar on one row"}:::annotation{x=68 y=33.1 w=13.3 h=16 mark="highlight"}Moon and Vibes are in here now.::::::annotation{x=92.582.5 y=33.1 w=10.9 h=16 mark="check" color="green"}**Apply** fits on the first row.:::::The numbers didn't move:| Pair | Before | After || --- | --- | --- || Pizzas vs. merged PRs | 0.95 | 0.95 || Rubber ducks vs. bugs fixed | 0.97 | 0.97 || Drizzle vs. standup minutes | 0.84 | 0.84 |::diff{label="Suggested change"}```css [toolbar.css].filters { flex-wrap: wrap; }``````css.filters { flex-wrap: nowrap; }```::No problems
12- 1Moon and Vibes are in here now.
- 2Apply fits on the first row.
The numbers didn't move:
| Pair | Before | After |
|---|---|---|
| Pizzas vs. merged PRs | 0.95 | 0.95 |
| Rubber ducks vs. bugs fixed | 0.97 | 0.97 |
| Drizzle vs. standup minutes | 0.84 | 0.84 |
| .filters { flex-wrap: |
| .filters { flex-wrap: nowrap; } |
Share it on Drop
Section titled "Share it on Drop"Drop renders these documents as a page your team comments on, and connects to Claude Code, Codex, or any MCP agent.
- Your agent drops the review.
- You comment on the exact spot.
- Your agent reads them and drops the next version.