Skip to main content

MarkDoc

npm add @markdoc/markdoc
import Markdoc from '@markdoc/markdoc';

const source = `
---
title: Doc title
---

# {% $markdoc.frontmatter.title %} {% #overview %}

{% callout type="check" %}
More content
{% /callout %}
`;

const ast = Markdoc.parse(source);
const content = Markdoc.transform(ast, {
nodes: {
heading: {
render: 'Heading',
attributes: {
id: { type: String },
level: { type: Number },
},
},
},
tags: {
callout: {
render: 'Callout',
attributes: {
title: {
type: String,
description: 'The title displayed at the top of the callout',
},
},
},
},
variables: {
author: {
name: 'Wener',
},
},
functions: {
includes: {
transform(parameters, config) {
const [array, value] = Object.values(parameters);

return Array.isArray(array) ? array.includes(value) : false;
},
},
},
partials: {
'header.md': Markdoc.parse(`# My header`),
},
});

// toHTML
const html = Markdoc.renderers.html(content);
// React
const children = Markdoc.renderers.react(content, React, { components });

语法

<!-- Tag+属性 -->
{% callout type="check" %}
More content
{% /callout %}

{% image src="" /%}

<!-- Annotation -->
# Header {% #custom-id %}
# Heading {% .custom-class-name-here %}

<!-- 变量 -->
{% $variable %}
{% $markdoc.frontmatter.title %}

<!-- 函数 -->
# {% titleCase($markdoc.frontmatter.title) %}

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

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

FAQ

Why not MDX

  • MDX
    • 允许任意 JS - docs as code
    • 允许任意代码导致最终会过度复杂
    • 要求语法严格正确 - 错误无法编译 - 例如: 不允许单独存在 < - 会导致解析错误
  • Markdoc
    • 限定允许的 tag - docs as data
    • declarative
    • 针对文档书写
    • 允许一定的错误语法