Markdoc 使用教程

项目介绍

Markdoc 是一个基于 Markdown 的语法和工具链，用于创建自定义的文档站点和体验。它被设计用来支持 Stripe 的公共文档，这是一个最大且最复杂的文档站点。Markdoc 扩展了标准的 Markdown 语法，增加了标签和注释等功能，使得文档编写更加灵活和强大。

项目快速启动

安装

首先，你需要安装 Markdoc 库。你可以使用 npm 或 yarn 进行安装：

npm install @markdoc/markdoc

或者

yarn add @markdoc/markdoc

使用示例

安装完成后，你可以在你的应用中导入并使用 Markdoc。以下是一个简单的示例：

const Markdoc = require('@markdoc/markdoc');

// 或者使用 ES 模块
// import Markdoc from '@markdoc/markdoc';

const doc = `
# Markdoc README
[% image src="/logo.svg" /%]
`;

const ast = Markdoc.parse(doc);
const content = Markdoc.transform(ast);

// 如果你使用 React
return Markdoc.renderers.react(content, React);

应用案例和最佳实践

应用案例

Markdoc 被广泛应用于需要高度定制化的文档站点，特别是在需要支持复杂内容结构和交互的场景中。例如，Stripe 使用 Markdoc 来构建其公共文档站点，该站点不仅包含大量的文档内容，还支持多种交互功能，如搜索、导航和内容过滤。

最佳实践

1. 模块化内容：将文档内容模块化，便于管理和复用。
2. 使用标签和注释：利用 Markdoc 提供的标签和注释功能，增强文档的表达能力。
3. 集成 React：如果你使用 React 框架，可以利用 Markdoc 的 React 渲染器，将文档内容无缝集成到你的应用中。

典型生态项目

1. Markdoc + React

Markdoc 与 React 的结合非常紧密，通过使用 Markdoc 的 React 渲染器，你可以轻松地将 Markdown 文档转换为 React 组件，从而实现动态文档内容。

2. Markdoc + Next.js

Next.js 是一个流行的 React 框架，支持服务器端渲染和静态站点生成。结合 Markdoc，你可以创建一个动态且高效的文档站点。

3. Markdoc + TypeScript

Markdoc 支持 TypeScript，通过 TypeScript 的类型检查，可以提高文档内容的可靠性和开发效率。

通过以上模块的介绍，你应该能够快速上手并使用 Markdoc 来构建你的文档站点。