Markup language

Inline formatting

Within any line, you can add bold, italic, and inline code formatting. This works inside any text-bearing prefix type.

Inline code uses single backticks and renders in a monospace font with a subtle tinted background. Code spans never process formatting inside, so `*literal*` stays literal. Escape a delimiter with a backslash: \*, \`, or \\.

Formatting markers are stripped in the rendered view and in fuzzy matching, so **bold** matches bold when checking off tasks or searching.

Lists and indentation

Bullet lists use *, numbered lists use %. To nest a list, indent two spaces per level. Up to five levels of nesting are supported.

Escaping and comments

Two prefixes keep Mudlark from interpreting a line. \ makes the rest of the line plain text, so \ + Not a task renders as the literal text “+ Not a task”. / marks a comment, a private note that stays in the left pane and never appears in the rendered note.

Smart matching

When you check off a task with - or move something with >, you don’t need to type the full name. Each word you type just needs to match the beginning of a word in the original, in order.

This also works with filenames and paths. A file like images/daisy-pants-stereo.jpg is broken up at slashes, dots, and dashes, so _ @ pants is enough to match it.

The editor colors the line live as you type: green when it finds exactly one match, yellow when more than one item matches (ambiguous, so nothing happens), and red when nothing matches.

Checking off tasks

- looks for a matching task and marks it done. Content after the space is the task name to match.

In the rendered pane, clicking a task checks it off by writing a matching - line. Clicking again clears it. Cmd-click copies the task text instead.

Removing items and sections

To remove any other kind of item, use _ followed by the type’s prefix. Works with Heading, Task, Highlight, Quote, Bullet, Numbered, Media, Code, Math, Timer, Table, Footnote.

Use _ # name to remove an entire section and everything in it.

Moving things around

The > character moves content between sections.

Move an item here

Add a type prefix and a fuzzy match. The matched item moves into the current section.

Send an item to a heading

Add @ and a destination heading.

Relocate a whole section

Use the heading prefix # inside the move to target a heading by name. Without a destination, the matched heading and its contents re-parent into the current section. With @ destination, they re-parent under that heading instead.

A fourth form moves a whole named block. See Acting on a whole block.

Writing to another section

The . character creates a new item under another heading without moving your cursor. Write the content, then @ and the destination heading. An optional type prefix sets the item type; without one, the line is written as plain text.

> moves an existing item. . creates a new one. Without an @ destination, nothing is created.

Finding and replacing

The , character searches everything above it. Add a pipe to replace matches, a type prefix to target a specific type, or @ heading to scope the search to a specific section.

Rules as barriers

The ~ character draws a horizontal rule. Add a label to center text on the rule: ~ Chapter 2. A rule is also a barrier. Completions and moves cannot cross it: a - task below a rule cannot check off a task above it. Use one to fence off finished work.

Opening and closing a block

Double a block-capable prefix to open a block. Use the same doubled prefix again to close it. Single-prefix lines stay as typed-line shortcuts.

Block-capable types: ++ !! "" ** %% `` == :: && // ^^.

Named blocks

Give a block a title by writing the doubled prefix followed by a name. Named blocks show up as groups on the right side, and you can check off, remove, or move the whole group at once.

-- Shopping marks all items done. > ++ Shopping moves the entire block.

Acting on a whole block

A single type prefix targets one item. Doubling the inner prefix targets a whole named block.

The same doubling works inside action lines. _ + milk removes one item and _ ++ Shopping removes the block. > + milk moves one item and > ++ Shopping @ Home moves the block under “Home”.

These commands look upward from where you type and stop at the nearest ~ rule. If two blocks with the same name are both in reach, Mudlark does nothing rather than guess.

Composite blocks like code, tables, and math can only be targeted this way: by name, with the doubled form.

Container and composite blocks

Blocks come in two kinds. Inside a container block (++, **, %%), every line is still its own item. You can check off one task inside a ++ block with a plain - milk.

A composite block (!!, "", code, math, tables, media) is one unit. Its inner lines cannot be targeted on their own. To complete, move, or remove it, use its name with the doubled form.

Code blocks

A code block can carry both a language hint and a title. Write the language right after the doubled backtick (no space), then a space, then the title.

The language drives syntax highlighting. The title renders as a header on the rendered block. A bare ``swift opens an unnamed block. A bare `` opens an unnamed, untyped block.

Block hints

A few block prefixes accept a hint glued to the opener, with no space between them. Code takes a language: ``swift Login flow. Math takes an aggregator: ==sum totals. Tables take a format: &&csv. Other prefixes accept the bare doubled form with an optional name only.

Countdowns

Write a duration after the prefix. Units are hours, minutes, and seconds, in long or short form, and a bare number is minutes. Text after the duration names the timer.

A timer can run several phases in a row. Separate them with commas and give each an optional name: : 25m work, 5m rest. In the rendered pane, clicking a timer resets it and starts it again.

Repeating timers

:repeat starts the timer over each time it finishes and cycles forever. Glue a count from 1 to 9999 to the word and it stops after that many cycles. While it runs, the rendered pane shows the cycle beside the phase name, as in 2 of 4.

The count has to touch the word. With a space, as in :repeat 4 5m, the 4 is read as part of the duration.

Alarms

:alarm waits for a time of day, a date, or both. Until the last hour it shows the target in the muted style. During the last hour it counts down, and for a minute after firing it shows 0:00. A time on its own means the next time the clock reads that, today or tomorrow, so the alarm comes back every day. A date fires once, at the start of the day unless you add a time, and afterwards shows its target struck through.

Clicking an alarm does nothing, and Restart timers leaves it where it is.

Counting up from a date

:since counts up from a date, a time, or both. With a date alone it shows Day N, and the anchor day is Day 1. With a time it shows the hours and minutes that have passed, and after 24 hours it shows the days as well. A time on its own means the most recent time the clock read that, today or yesterday.

A since line never notifies and never brings up the full-pane timer view. A date or time in the future is an error.

Writing dates and times

Alarms and since lines take a date as YYYY-MM-DD, a time as H:MM on the 24-hour clock, or both with a space between, then an optional name. Nothing else is accepted in a note. Words like 3pm and tomorrow, and a time that does not exist, like 25:99, show an error in place of the clock that names the accepted shape.

The capture bar, the mudlark:// URL scheme, and the Shortcuts actions accept relative words and write the absolute form into the note. :since now becomes today’s date and the current time, and :alarm tomorrow 3pm standup becomes tomorrow’s date, 15:00, and the name. In the editor, typing :since and a space offers the current date and time as a completion.

Timer blocks and inline timers

Doubled :: opens a timer block, with an optional name: :: Workout. The mode words work on blocks too: ::repeat Workout, ::repeat4 Tabata, ::alarm Meetings, and ::since Habits. Each line inside is one timer, written without the prefix: a duration in a countdown or repeat block, a date or time in an alarm or since block. Every kind closes with a bare ::.

Inside a sentence, the same forms are {: 5m}, {:repeat 1hr}, {:repeat4 30s}, {:alarm 15:30}, and {:since 2026-06-01}. See Inline embeds.

Notifications

Notifications are off by default. Turn on Notify when a timer finishes or an alarm fires, under Timers in Appearance settings. macOS asks for permission once. If you decline, the setting shows a link to System Settings, where you can allow notifications for Mudlark later.

A countdown notifies when it reaches zero, with Restart and Open note buttons. An alarm notifies at its time, once for a date and every day for a time on its own, with an Open note button. A repeat with a count notifies once, when its last cycle ends. A repeat without a count and a since line never notify. When the note is on screen in the front window, you hear the sound and no banner appears. Clicking a notification opens the note.

Note links

Write [[Title]] anywhere inside a line to link to another note in the same vault. Typing [[ opens an autocomplete of vault titles. Pick one and the closing ]] is inserted for you.

In the editor, the link shows as a compact chip. Move your caret into it and it turns back into the raw [[Title]] text for editing. In the right pane the chip is clickable and jumps to the linked note.

A note link on its own line renders as a preview card in the right pane. The layout follows the link: [[Title]] previews the whole note, [[#Heading]] previews that heading in the current note, and [[Title#Heading]] previews the heading in another note. A fragment that matches no heading falls back to the whole-note preview.

Renaming or moving a note auto-rewrites every [[ ]] reference across the vault, so links stay valid without manual cleanup. On export, each link resolves to the destination’s native note-link form (a Markdown link by default, a wiki-style link for Obsidian, an internal link for Notion, and so on). See the export guide for the per-destination behavior.

Inline embeds

The { … } notation embeds something live inside a sentence: an image, a calculation, a code snippet, or a timer. The first character inside the braces is the same prefix you would use to open that item on its own line. Four types embed:

Inline math

{= expression} places a calculated value inside a line. See the math and formulas guide for expressions, units, functions, and table formulas.

Inline code

{`code} renders monospaced code inline. Glue a language hint to the backtick for syntax highlighting: {`python def f()} highlights as Python. Inline code is for short snippets that want richer treatment than the backtick-wrapped `text` inline-formatting shortcut.

Inline media

{@ filename} drops a piece of media into the sentence. Typing {@ opens an autocomplete of vault media. Local images render in place, sized to the column, with rounded corners, an accessibility label from the filename, and a click action (click to open, Cmd-click to copy). Remote URLs load asynchronously. Videos play inline. A click starts or pauses playback.

For a gallery, open a media block with @@ and put one media reference per line. The right pane lays the items out in a mosaic of justified rows sized from each image’s aspect ratio, with runs of tall images stacked so they sit beside shorter neighbors. Nothing is cropped or squeezed to a uniform tile.

Inline timers

{: 25:00 Focus} for a countdown, {:repeat 5m} for a repeating timer, {:repeat4 30s} for one that stops after four cycles, {:alarm 15:30} for an alarm, and {:since 2026-06-01} for a day counter. The rendered pane shows an icon and the clock, ticking in real time. Bare numbers can carry a phase name, so {: 25 Focus} reads as 25 minutes. Inline timers are for when a timer wants to live inside a sentence. Full-line timers are covered in Timers.

Where embeds work

Embeds and [[note links]] work inside prose: headings, tasks, highlights, quotes, bullets, numbered items, footnote definitions, and custom callouts. They also work in table cells: math evaluates, note links and inline code render, and inline timers count down live. Media and metadata embeds in a cell stay as source text. A pipe inside an embed or a [[Note|Alias]] link does not split the cell. Inside code blocks, full-line math, media lines, and comments, the braces stay literal text. Braces that do not form an embed stay ordinary text, and inline formatting still works inside them. To keep an embed-shaped span literal, escape the opening brace with \{.

Footnotes

Put a ^ at the end of a word, with no space, to mark a footnote. Then define the note on its own line with ^ text.

The first marker pairs with the first definition, the second with the second, and so on. In the rendered pane this becomes “The cat sat on the mat.¹” with a numbered footer below the section. Unpaired markers render as ˣ.

For longer notes, open a footnote block with ^^.

A footnote block renders as a callout in the right pane. The footnote number sits in the block’s header, so the body reads on its own. Escape a marker with \^ to render a literal caret. In Settings → Markup, you choose where footnote definitions appear: in the body, next to the reference, or in a footer at the end of the section.