跳到正文

Markdoc 语法

Markdoc 语法是 Markdown 的超集，具体遵循 CommonMark 规范。Markdoc 为语法添加了一些扩展，例如标签和注释，我们将在下文描述。这些扩展实现了 Markdoc 强大的可扩展性模型。

有关 Markdoc 标签语法的形式化语法，请参阅 Markdoc 语法规范。

节点

节点是 Markdoc 从 Markdown 继承的元素，你可以使用注释来自定义它们。

# 标题

**粗体**

_斜体_

[链接](/docs/nodes)

![图片](/logo.svg)

列表
- 项目 1
- 项目 1
- 项目 1

> 引用

`行内代码`

```
代码块
```

标题

粗体

斜体

链接

列表

  • 项目 1
  • 项目 1
  • 项目 1

引用

行内代码

代码块


更多信息，请参阅节点文档。

标签

标签是 Markdoc 在 Markdown 基础上添加的主要语法扩展。每个标签由 {% 和 %} 括起来，包含标签名、属性和内容主体。

与 HTML 类似，你可以嵌套 Markdoc 标签，并使用属性自定义它们。

{% tag %}
内容
{% /tag %}


更多信息，请参阅标签文档。

属性

向节点和标签传递属性以自定义其行为。你可以传递以下类型的值：number、string、boolean、JSON array 或 JSON object，可以直接传递或使用variables。

对于标签，你可以使用类似 HTML 的语法：

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

注释

由于类似 HTML 的语法不适用于节点，我们提供了另一种选项，称为_注释_：将属性写在标签或节点之后，用另一组 {% 和 %} 括起来。

{% table %}

- 函数 {% width="25%" %}
- 返回  {% colspan=2 %}
- 示例  {% align="right" %}

{% /table %}


更多信息，请参阅属性文档。

变量

Markdoc 变量允许你在运行时自定义 Markdoc 文档。所有变量都有 $ 前缀。

这里我正在渲染一个自定义的 {% $variable %}

变量必须包含可 JSON 序列化的内容，例如字符串、布尔值、数字、数组和 JSON 对象。
你可以使用点表示法访问嵌套值，类似于 JavaScript：

这是一个深度嵌套的变量 {% $markdoc.frontmatter.title %}

你可以在整个文档中使用变量作为内容本身：

© {% $currentYear %} Stripe


更多信息，请参阅变量文档。

函数

函数的外观和行为类似于 JavaScript 函数。你可以从文档正文、注释内部或标签属性中调用它们。函数参数以逗号分隔。函数调用不支持尾随逗号。

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

{% if equals(1, 2) %}
显示密码
{% /if %}

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


更多信息，请参阅函数文档。

注释

Warning

注意：当前注释支持需要向 Markdoc.Tokenizer 传递 allowComments: true。
在未来的 Markdoc 版本中，这将默认启用。

Markdoc 支持 Markdown 注释语法，你可以向文档添加注释，而不会使内容显示在可渲染输出中。

<!-- 注释写在这里 -->

后续步骤