The Markdoc syntax

Markdoc syntax is a superset of Markdown, specifically the CommonMark specification. Markdoc adds a few extensions to the syntax, such as tags and annotations, which we describe below. These extensions enable Markdoc's powerful extensibility model.

For a formal grammar of the Markdoc tag syntax, refer to the Markdoc syntax spec.

Nodes are elements that Markdoc inherits from Markdown, which you can customize with annotations.

# Headers

**Bold**

_Italic_

[Links](/docs/nodes)

![Images](/logo.svg)

Lists
- Item 1
- Item 1
- Item 1

> Quotes

`Inline code`

```
Code fences
```

Code fences

For more information, check out the Nodes docs.

Tags are the main syntactic extension that Markdoc adds on top of Markdown. Each tag is enclosed with {% and %}, and includes the tag name, attributes, and the content body.

Similar to HTML, you can nest Markdoc tags, and customize them with attributes.

{% tag %}
Content
{% /tag %}

For more information, check out the Tags docs.

Pass attributes to nodes and tags to customize their behavior. You can pass values of type: number, string, boolean, JSON array, or JSON object, either directly or using variables.

With tags, you can use an HTML-like syntax:

{% city
   index=0
   name="San Francisco"
   deleted=false
   coordinates=[1, 4, 9]
   meta={id: "id_123"} 
   color=$color /%}

Because the HTML-like syntax doesn't work with nodes, we offer another option, called annotations: write the attributes after the tag or node you're passing them to, in a separate set of {% and %}.

{% table %}

- Function {% width="25%" %}
- Returns  {% colspan=2 %}
- Example  {% align="right" %}

{% /table %}

For more information, check out the Attributes docs.

Markdoc variables let you customize your Markdoc documents at runtime. Variables all have a $ prefix.

Here I am rendering a custom {% $variable %}

Variables must contain JSON-serializable content, such as strings, booleans, numbers, arrays, and JSON objects.
You can access nested values using dot-notation, similar to JavaScript:

Here's a deeply nested variable {% $markdoc.frontmatter.title %}

You can use variables throughout your document, as content itself:

© {% $currentYear %} Stripe

For more information, check out the Variables docs.

Functions look and feel similar to JavaScript functions. They're callable from the body of the document, inside an annotation, or within tag attributes. Function parameters are comma-separated. Trailing commas aren't supported in function calls.

# {% titleCase($markdoc.frontmatter.title) %}

{% if equals(1, 2) %}
Show the password
{% /if %}

{% tag title=uppercase($key) /%}

For more information, check out the Functions docs.

Markdoc supports Markdown comment syntax adding comments to your documents without having the content show up in the renderable output.

<!-- comment goes here -->

• Render Markdoc
• Validate your content