Markdoc 新一代Markdown文档内容发布框架
今天给大家介绍的主题是 Markdoc，即由 Stripe 开发的一种基于 Markdown 的文档格式和内容发布框架。
Markdoc官网：https://markdoc.dev/
什么是 Markdoc
Markdoc 是一种基于 Markdown 的文档格式和内容发布框架， 它由是 Stripe 内部设计的，以满足面向用户的产品文档的需求。 Markdoc 使用标签和注释的自定义语法扩展了 Markdown，提供了一种为个人用户定制内容并引入交互元素的方法。
可以通过如下方式快速使用 Markdoc：
npm install @markdoc/markdoc
// 或者
yarn add @markdoc/markdoc
安装后就可以在代码中直接引用：
const Markdoc = require('@markdoc/markdoc');
//或者
import Markdoc from '@markdoc/markdoc';
然后调用 parse, transform 和 render 函数来渲染内容。
const source = '# Markdoc';
const ast = Markdoc.parse(source);
const content = Markdoc.transform(ast, /* config */);
const html = Markdoc.renderers.html(content);
目前 Markdoc 在 Github 上有 6.2k 的 star、150+ 的 fork、超过 1k 的项目依赖它，是一个值得长期关注的前端项目。
Markdoc 如何工作
Markdoc 的三大渲染器
按照设计，Markdoc 不是一种成熟的模板语言，并且不允许混合任意代码和内容。 然而，它是一种完全声明的格式，从上到下都是机器可读的：它解析为可以遍历的数据结构，以支持强大的静态分析、验证和程序化内容转换。
Markdoc 渲染器解释自定义标签和节点定义，将文档数据结构转换为可渲染节点树，最终转换为所需的输出格式。 Markdoc 框架目前包括三个渲染器：
- 一个 HTML 字符串渲染器
- 一个将文档转换为 JavaScript 代码的静态 React 渲染器
- 一个将可渲染树节点直接转换为 React 元素的动态 React 渲染器
Markdoc 的 React 渲染器使在 Markdown 内容中使用 React 组件成为可能，其支持选项卡切换器和可折叠部分等交互功能。 可以实现引入对其他输出格式和客户端框架的支持的自定义渲染器。
解析器生成器 PEG.js
PEG.js 是一个简单的 JavaScript 解析器生成器，可生成具有出色错误报告的快速解析器。开发者可以使用它来处理复杂的数据或计算机语言，并轻松构建转换器、解释器、编译器和其他工具。
PEG.js 具有以下显著特征：
- 简单而富有表现力的语法
- 集成词法和句法分析
- 解析器具有开箱即用的出色错误报告
- 基于解析表达式语法形式主义——比传统的 LL(k) 和 LR(k) 解析器更强大
- 可从浏览器、命令行或通过 JavaScript API 使用
目前 PEG.js 在 Github 上有 4.6k 的 star、450+ 的 fork、191k 的项目依赖它。可以使用下面的示例快速使用 PEG.js：
npm install -g pegjs
$ pegjs -o arithmetics-parser.js arithmetics.pegjs
markdown-it 的助力
Markdoc 的解析器建立在一个名为 markdown-it 的流行开源 Markdown 库之上。 Markdoc 使用 markdown-it 作为标记器，从 markdown-it 输出的标记数组构建抽象语法树 (AST)。
Markdown-it 解析器的特性包括：具有 100% CommonMark 支持、 扩展支持、语法插件、安全和极致的速度。目前 Markdown-it 在 Github 上有 15.2k 的 star、1.6k 的 fork、432k 的项目依赖它。可以使用下面的示例快速使用 markdown-it：
// node.js经典方式
var MarkdownIt = require('markdown-it'),
md = new MarkdownIt();
var result = md.render('# markdown-it rulezz!');
// node.js的语法糖
var md = require('markdown-it')();
var result = md.render('# markdown-it rulezz!');
// 没有 AMD 的浏览器，在脚本加载时添加到 window
// 注意，“markdownit”中没有破折号。
var md = window.markdownit();
var result = md.render('# markdown-it rulezz!');
Markdoc 的自定义标记语法在 markdown-it 插件中实现， 解析标记语法的逻辑是从 peg.js 语法生成的。 Markdoc 有自己专用的渲染架构，而不是依赖 markdown-it 来生成它的输出。 为了处理 Markdoc 的自定义标签和支持多种输出格式，其开发了一个独立的渲染系统。
Markdoc 在 Markdown 中添加标记
Markdoc 选择 Markdown 作为起点，因为它易于阅读和推理，许多工程师和技术作家已经非常熟悉，并且得到众多现有工具的大型生态系统的广泛支持。 然而，Markdown 本身并不适合编写复杂的、高度结构化的内容，如文档等等。
Markdoc 提供了一个可扩展的系统，用于定义可以在 Markdown 内容中无缝使用的自定义标签。 使用自定义标记语法，开发者能够表达更精细的文档层次结构，插入交互式组件，并支持条件内容、内容包含和变量插值等功能。 Markdoc 对 Markdown 语法的扩展被设计为可组合且侵入性最小，在不影响可读性的情况下提供关键功能。
比如下面示例使用 .my-class-name 和 #my-id 作为 class=my-class-name 和 id=my-id 的简写。
# Examples {% #examples %}
{% table .striped #exampletable %}
- One
- Two
- Three
{% /table %}
Markdoc 也允许开发者为每个标签配置自定义属性类型，比如以下示例定义了 Callout 标记的属性。 默认情况下，该属性设置为注意并根据匹配数组进行验证。
{
render: 'Callout',
children: ['paragraph', 'tag', 'list'],
attributes: {
type: {
type: String,
default: 'note',
required: true,
matches: ['caution', 'check', 'note', 'warning'],
errorLevel: 'critical',
},
}
};
在 React 中使用 Markdoc
Markdoc 支持使用 React 开箱即用地渲染 Markdoc 语法。按照以下步骤使用 create-react-app 和 express 构建 Markdoc 应用程序。
按照 create-react-app 入门步骤创建初始应用程序
设置 Markdoc 架构
schema/
├── Callout.markdoc.js
└── heading.markdoc.js
schema/Callout.markdoc.js 的内容如下：
// schema/Callout.markdoc.js
module.exports = {
render: 'Callout',
children: ['paragraph', 'tag', 'list'],
attributes: {
type: {
type: String,
default: 'note',
matches: ['check', 'error', 'note', 'warning'],
},
},
};
schema/heading.markdoc.js 的内容如下：
// schema/heading.markdoc.js
const { nodes } = require('@markdoc/markdoc');
function generateID(children, attributes) {
if (attributes.id && typeof attributes.id === 'string') {
return attributes.id;
}
return children
.filter((child) => typeof child === 'string')
.join(' ')
.replace(/[?]/g, '')
.replace(/\s+/g, '-')
.toLowerCase();
}
module.exports = {
...nodes.heading,
transform(node, config) {
const base = nodes.heading.transform(node, config);
base.attributes.id = generateID(base.children, base.attributes);
return base;
},
};
解析服务器上的 Markdoc 文档
// ...
const rawText = fs.readFileSync(file, 'utf-8');
const ast = Markdoc.parse(rawText);
在服务端调用 Markdoc.transform
// server.js
const express = require('express');
const app = express();
const callout = require('./schema/callout.markdoc');
const heading = require('./schema/heading.markdoc');
// ...
app.get('/markdoc', (req, res) => {
const ast = contentManifest[req.query.path];
const config = {
tags: {
callout,
},
nodes: {
heading,
},
variables: {},
};
const content = Markdoc.transform(ast, config);
return res.json(content);
});
app.listen(4242, () => {
console.log(`Example app listening on port ${4242}`);
});
在客户端调用 Markdoc.renderers.react
// src/App.js
import React from 'react';
import Markdoc from '@markdoc/markdoc';
import { Callout } from './Callout';
export default function App() {
const [content, setContent] = React.useState(null);
React.useEffect(() => {
(async () => {
const response = await fetch(
`/markdoc?` + new URLSearchParams({ path: window.location.pathname }),
{ headers: { Accept: 'application/json' } }
);
if (response.status === 404) {
setContent('404');
return;
}
const content = await response.json();
setContent(content);
})();
}, []);
if (content === '404') {
return <p>Page not found.</p>;
}
if (!content) {
return <p>Loading...</p>;
}
const components = {
Callout,
};
return Markdoc.renderers.react(content, React, { components });
}
启动客户端和服务器
npm run start:client
npm run start:server
除了与React集成外，Markdoc还支持与HTML、Next.js等集成。
参考资料
https://markdoc.dev/docs/overview
https://github.com/markdown-it/markdown-it
https://pegjs.org/
https://github.com/pegjs/pegjs
https://markdoc.dev/docs/attributes
https://stripe.com/blog/markdoc
https://markdoc.dev/docs/examples/react#setup
https://transloadit.com/blog/2022/06/devtimes-055/
湘公网安备 43102202000103号