How Remarkd thinks about a document.

Human-first by design

The guiding rule is that the source should be pleasant to read on its own. A note is the word NOTE: in front of a sentence. A quote is text between two underscore rules. A tab group is a few lines each introduced by a short marker. Nothing requires you to open an angle bracket, and a reviewer reading the raw .remarkd file in a pull request can still follow the document.

Because the format is plain text, it diffs cleanly, pastes anywhere, and never depends on a build step to stay legible. Rendering to HTML is a convenience, not a prerequisite for understanding.

The document model

A parse produces one section wrapper — <div class="remarkd-section section--level0 …"> — containing the rendered blocks. Everything inside is either a block or inline content:

• Blocks are paragraph-level structures separated by blank lines: paragraphs, headings, lists, tables, quotes, code fences, containers. A block often owns a region delimited by a fence (for example ____ for a quote or |=== for a table).
• Inline content is the formatting that lives inside a block's text: strong, emphasis, links, code spans, keyboard keys, footnotes, and so on. Inline rules run inside paragraphs, list items, table cells, and admonitions.

Blank lines are the primary separator. A line on its own that begins a fence opens a block; the matching fence closes it. This is why most Remarkd blocks are symmetrical — the same marker opens and closes them.

Block titles, roles, and attributes

Two one-line prefixes decorate the block that follows them:

• A line starting with a dot, like .Release Matrix, gives the next block a title.
• A bracketed line, like [.lead], attaches a role (a CSS class) or other block attributes to the next block.

They compose: a .Title line followed by a [.role] line followed by a paragraph produces a titled, classed paragraph. Tables, images, and containers use the same title mechanism. See Block title & roles and the table for worked examples.

Document attributes & substitution

An attribute line defines a named value for the rest of the document:

:product: Remarkd
:version: 1.0

{product} {version} keeps text readable.

A reference like {product} is replaced with its value during parsing. Attributes are useful for product names, URLs, and version numbers you would otherwise repeat. In document-header mode (a developer option) the parser also reads attributes from the leading header block. See Document attributes.

Conditionals

The PHP parser supports AsciiDoc-style conditional directives that include or drop content based on document attributes. They are driven by the same attributes described above:

:flag:

ifdef::flag[]
Shown only when "flag" is defined.
endif::[]

ifndef::flag[Shown inline only when "flag" is NOT defined.]

The validators are ifdef (defined), ifndef (not defined), iftrue, iffalse, ifempty, and ifnempty (not empty); ifeval evaluates a simple comparison. Conditions combine with + (and) and , (or), and a single-line form carries its content inside the brackets: ifdef::flag[inline content]. Close a block form with endif::[].

Conditionals are covered by the shared fixture suite and behave the same way in the PHP, Go, and TypeScript parsers.

Object macros

Where inline syntax stops, object macros take over. A macro is written {{name …attributes}} and expands to a self-contained piece of HTML. The built-in objects cover links, line breaks, anchors, progress meters, images, and video:

{{link:https://example.com text=Example target=_blank}}
{{anchor name=top}}
{{meter id=p min=0 max=10 value=7 text=7/10 label=Progress}}
{{video:dQw4w9WgXcQ source=youtube aspect=16:9}}

Macros accept positional values (after the colon), named attributes (key=value), and role hints (.class). The object macros and object macro attributes entries show the exact output, and video demonstrates aspect ratios and timing.

Source-backed references

Remarkd has first-class support for footnote-style references, which is handy for fact-checked or cited content. Mark a fact with {{ref content=… code=…}} and emit the numbered list anywhere with {{reflist}}:

The sky is blue{{ref content=Rayleigh scattering code=sky}}.

# Sources

{{reflist}}

Each reference becomes a superscript link tied to a numbered list item, with anchors connecting the two directions. See References for the rendered result.

Composing a document

These pieces stack. A typical guide opens with a title and a lead paragraph, defines a couple of attributes, explains concepts in prose with the occasional NOTE:, walks through a procedure as steps or tabs, shows commands in code fences, and closes with a reference list. None of it requires HTML, and all of it stays readable in the source.