---
html: true
title: Darkmown docs
description: Learn Darkmown routing, directives, state, loops, forms, and the static-to-reactive model.
transitions: true
schema: TechArticle
---
@include /nav.wd
@include /base.wd
Documentation
# The Darkmown docs
Darkmown is a Markdown-native framework for mostly-static sites with tiny reactive islands. Pages are plain files: `.md` stays pure CommonMark, and `.wd` ("whateverdown") is the same Markdown plus first-party directives.
Every heading on every page gets a stable, GitHub-style `id` at build time (lowercased, punctuation stripped, duplicates deduped), so the links above — and deep links into any Darkmown page — are plain `#` anchors with zero JavaScript.
@include ./-relative-note.wd
## Install
```sh
npx @zvndev/darkmown init my-site
cd my-site
npm install
npm run dev
```
Or add Darkmown to an existing project with `npm install -D @zvndev/darkmown`. The package is scoped; the command it installs is plain `darkmown`.
Want to try the syntax before installing anything? The [playground](/playground/) compiles `.wd` and `.md` live in your browser — the same compiler the CLI ships — and shows the real `file:line` error when you break something.
For editing, there is a VS Code extension for `.wd` and `.skin` files: see [Editor support](#editor-support).
`darkmown dev` rebuilds incrementally: it tracks which routes depend on each file (includes, colocated assets, loop data, collections), so editing one page or include recompiles only the routes it affects — and falls back to a full rebuild whenever a file is added, removed, or renamed. `routes.json`, the sitemap, and the RSS feed are regenerated on every rebuild, so they always describe the whole site.
## The two formats
- `.md` is strict CommonMark. Directives, includes, and `{ bindings }` stay plain text, and the build prints a hint if it spots `.wd` syntax in a `.md` file.
- `.wd` is Markdown plus directives. Renaming a file from `.md` to `.wd` is the upgrade path — nothing else changes.
## Routing rules
- `site/pages/index.wd` becomes `/`.
- `site/pages/docs/index.wd` becomes `/docs/`.
- `.secret.wd`, `-draft.wd`, and hidden folders do not become pages.
- `site/_/` is the include shelf, never a route.
## Directive lines
A directive is a whole line, written flush against the left margin. Four rules cover what the compiler will and will not accept there.
- **One directive per line, unindented.** An indented `:state` (inside a list item, say) is prose, and a directive inside a fenced code block is code.
- **A bare keyword is an error.** A line that is exactly `:state`, `:button`, `@loop`, or any other directive that takes arguments used to render as literal text with no warning at all. It now reaches that directive's own handler and fails with that directive's coded message and `Use:` hint, so a lone `:state` gives `[WD201]` and a lone `:button` gives `[WD301]`. Three keywords stay valid bare, because they mean something bare: `:::` opens or closes a container, `:theme` declares the theme store, and `:carousel` opens a carousel with no autoplay.
- **To show a directive name as text, escape it.** Writing `\:fetch` renders the literal text `:fetch`. It is the ordinary CommonMark backslash escape, so it works anywhere Markdown does.
- **There is no comment syntax.** A trailing `#` or arrow note on a directive line is parsed as part of the value, not as a comment: `html: true (required)` seeds the string `true (required)`, which compiles clean while doing the opposite of what it looks like. Put explanations in the prose around the line.
## Includes
- `@include /nav.wd` resolves from `site/_`.
- `@include ./-relative-note.wd` resolves beside the current page.
- `@include /card.wd with title="Hello" count=3` passes values into the include.
- `with title={ feature.title }` passes a value already in scope — including whole objects.
- Includes inside a loop inherit the loop value automatically.
An include declares fallbacks for its `with` arguments in its own frontmatter with `defaults: [title="Untitled", cta="Learn more"]`. The caller's `with` value always wins; the default fills in when the caller is silent; an argument with neither renders as literal `{ title }` text, as before. Values are strings (frontmatter is string-typed), entries split on top-level commas only (so `cta="Learn more, today"` works), and a malformed `defaults:` is `[WD613]`.
The block form turns an include into a wrapper component. The lines between the call and `@endinclude` compile once in the **caller's** scope (its `:state`, and the loop item inside a `@loop`) and land wherever the include puts a standalone `{ children }` line:
```wd
@include /card.wd with title="Pricing"
Everything in **this paragraph** is the card body.
@endinclude
```
with `site/_/card.wd`:
```wd
---
defaults: [title="Untitled"]
---
::: card
## { title }
{ children }
:::
```
The slot is a standalone line only (mid-paragraph or fenced `{ children }` stays literal; on a top-level page it is literal too; a `.md` include cannot host one). Called without a block, the slot renders empty; a block given to an include that never uses `{ children }` is dropped with a build warning. `@endinclude` closes the nearest preceding unpaired `@include`, so an inline `@include` written between opener and closer consumes the pairing; one level of block nesting is supported (deeper is `[WD616]`), and a stray closer is `[WD614]`. There is deliberately no unclosed-block error: an unpaired opener is the inline form, and the inline form must stay legal. Per-row components in a loop are the payoff, and stay zero-JS over a static source:
```wd
@loop /products.json into product
@include /card.wd with title={ product.name }
Price: { product.price | money }
@endinclude
@endloop
```
## Loops
`@loop into ` is the only loop. The body is normal Markdown (or more directives) and repeats once per row:
```wd-fragment
@loop /features.json into card
@include /feature-card.wd
@endloop
```
The source decides how the loop behaves:
- A JSON file path (`/features.json`, `./data.json`) unrolls at build time — pure static HTML.
- An in-scope value (an include argument or an outer loop value) also unrolls at build time.
- A `:state` list compiles to a reactive region the runtime patches by key.
Loops nest, and `{ card.title }` style dotted paths reach into each row.
### Filtering with `where`
Add `where ` to filter a loop. Conditions join with `and` / `or`:
```wd-fragment
@loop /products.json into p where p.featured == true and p.price < 80
- { p.name }
@endloop
```
Operators are `==` `!=` `<` `<=` `>` `>=` and `contains` (case-insensitive substring). Operands are item fields, declared `:state`, numbers, or `"strings"` — a validated whitelist, never arbitrary code.
The predicate decides reactivity exactly like the source does: read only the row and the filter runs at build time (zero JS); read a `:state` value and the loop re-filters live. Pair it with `:bind` for a search box in pure Markdown:
```wd
:state products = [{"id":1,"name":"Aurora Lamp"},{"id":2,"name":"Briza Fan"}]
:state q = ""
:bind q placeholder="Search"
@loop products into p where p.name contains q
- { p.name }
@endloop
```
`:bind ` renders an `` wired two-way to a `:state` value — type and the list filters as you go.
### Editable lists with per-row actions
A `:button` inside a reactive loop can act on its own row — the basis for carts and to-do lists:
```wd
:state products = [{"id": 1, "name": "Aurora", "price": 49}]
:state cart = []
@loop products into product
::: card
**{ product.name }** — ${ product.price }
:button "Add to cart" -> cart += product
:::
@endloop
@loop cart into line
::: card
{ line.name }
:button "Remove" -> cart remove line
:::
@endloop
```
`cart += product` appends a copy of the current row to another `:state` list; `cart remove line` removes the current row from the list being looped. Both are checked against the enclosing loop at compile time — no JavaScript.
### Sorting, paging, and meta variables
Shape a loop with clauses in a fixed order after `into`: `where`, then `sort by`, `reverse`, `offset`, `limit`.
```wd-fragment
@loop /posts.json into post sort by post.date desc limit 5
{ $number }. { post.title }
@endloop
```
- `sort by [asc|desc]` — the key must start with the loop item (`post.date`). Numbers sort numerically; anything else sorts as text. `asc` is the default.
- `reverse` flips the order; `offset N` / `limit N` slice it. `N` can be an integer or a `:state`/`:store` key, which makes paging reactive (`limit pageSize`).
Every row exposes meta variables — `{ $index }` (0-based), `{ $number }` (1-based), `{ $first }`, `{ $last }`, `{ $count }` — usable in interpolation and `:if`:
```wd-fragment
@loop products into product
:if $first
**Top pick:**
:endif
{ $number } of { $count } — { product.name }
@endloop
```
### Empty lists with `@empty`
Add an `@empty` branch to render a fallback when the loop produces no rows (after filtering and slicing):
```wd-fragment
@loop todos into todo
- { todo.title }
@empty
Nothing left to do.
@endloop
```
A **missing** in-scope source is an empty list, not an error — `@loop meta.tags into tag` on a page whose frontmatter omits `tags` (an optional field) loops zero rows and renders the `@empty` branch. A value that is present but not a list is still a compile error with the file and line.
These clauses stay build-time when the source and every argument are static — a sorted, limited loop over a JSON file ships zero JS. The loop turns reactive only when the source or a clause reads `:state`/`:store`/`:fetch` data.
### Table rows from a loop
A **static** loop whose body is bare `| … |` cells fills a Markdown table. Write the header in prose and let the loop supply the rows:
```wd
| Item | Price |
| --- | --- |
@loop /products.json into row
| **{ row.name }** | { row.price } |
@endloop
```
That renders one `
` with one `
` per row, and each cell holds ordinary inline Markdown, links included. A format pipe works too, but its `|` has to be escaped inside a cell: `{ row.price \| money }`. Put the whole table inside the loop instead and you get a headerless table of the same shape; give the loop body its own `| --- |` separator and each row is a complete table, collapsed into one when the headers match.
Two limits to know before building on it:
- A pipe row written in prose **after** `@endloop` (a totals row) does not join the table. It stays a paragraph.
- A **reactive** loop over pipe rows is `[WD191]`, not silent breakage. A reactive row is cloned into a `