@canofold/markdown

English | 简体中文

@canofold/markdown 是可独立使用的 Markdown SDK。它提供 React 渲染、Markdown 与可信 MDX 的构建或 SSR、内容分析、结构样式和按行为加载的浏览器增强。视觉主题由 @canofold/themes 提供。

安装与渲染

pnpm add @canofold/markdown @canofold/themes react react-dom

import { Markdown } from '@canofold/markdown'
import '@canofold/markdown/base.css'
import '@canofold/themes/canofold.css'

export function Article({ source }: { source: string }) {
  return <Markdown source={source} />
}

公开入口

• @canofold/markdown 提供 React 渲染器和插件契约。
• @canofold/markdown/server 提供 Markdown 与可信 MDX 的构建或 SSR 渲染器。
• 服务端渲染器的 analyze() 返回编译后的内容事实及 assets 资源需求，不执行作者的 MDX 组件。宿主可在渲染页面前准备交互脚本和样式。
• @canofold/markdown/server/analyze 只分析文档能力，不执行渲染。
• @canofold/markdown/client 增强已经生成的静态 HTML。
• @canofold/markdown/base.css 提供 Markdown 结构与交互样式。
• @canofold/themes 提供主题契约和官方视觉主题；在 base.css 之后引入其中一个主题 CSS 入口。

在 Vite 等 bundler 中导入 @canofold/markdown/client 时，React 与 React DOM 继续由宿主应用的 peer dependency 提供，不会隐藏内置另一份 React。Canofold CLI 生成不依赖 bundler 的独立静态站点时，会自动选择自包含的本地浏览器资源；两种消费方式使用同一个公开入口，不需要用户配置 alias、import map 或运行时路径。

数学公式等可选语法由 @canofold/plugins 提供：

pnpm add @canofold/plugins

import { Markdown } from '@canofold/markdown'
import { math } from '@canofold/plugins'
import '@canofold/markdown/base.css'
import '@canofold/themes/canofold.css'
import '@canofold/plugins/math.css'

<Markdown source={source} options={{ plugins: [math()] }} />

渲染选项、MDX、写作语法、主题和浏览器增强见 Markdown SDK 文档。

编写预览可设置 options={{ directives: { invalid: 'literal' } }}，把格式错误或未知的富内容指令显示为转义后的原文，其余文档照常渲染。默认值仍为 error，构建时继续检查指令拼写。format:check 这样的普通冒号文本会保留为文本，除非该指令名属于内置语法或已由插件明确声明。此策略不会吞掉插件异常，也不会放宽 HTML 清理、媒体 URL 校验或 MDX 执行边界。

许可证：MIT