@luckyfishes/markdown-core 0.1.0 → 0.2.1

package/README.md

@@ -1,21 +1,406 @@
 # `@luckyfishes/markdown-core`
 
-Reusable Markdown/MDX parsing and AST transformation utilities extracted from `noname_blog`.
+一个可复用的 Markdown/MDX 语法解析与 AST 转换核心库，抽离自 `noname_blog`。
 
-This package only handles syntax parsing and AST transforms. It does not ship React components, styles, or framework-specific rendering glue.
+这个包只负责：
 
-## Included
+- 解析自定义 Markdown 语法
+- 在 remark / rehype 阶段转换 AST
+- 生成 MDX 组件节点或标准 HTML 节点
+- 提供目录提取等通用能力
 
-- Custom block syntax like `::tabs`, `::details`, and `::ComponentName`
-- Inline component syntax like `:badge[...]()` and `:tip[...]()`
-- Superscript and subscript transforms
-- Code fence to MDX component transforms
-- Footnotes heading normalization
-- Heading extraction helpers
+这个包**不负责**：
 
-## Not Included
+- React / Vue / Svelte 组件实现
+- MDX 运行时渲染
+- Next.js / React Markdown / Contentlayer 等框架集成
+- 样式、交互和主题
+- 业务组件本身的设计与行为
 
-- React component implementations
-- MDX runtime rendering
-- Next.js integration
-- CSS styles
+## 安装
+
+```bash
+npm install @luckyfishes/markdown-core
+```
+
+## 能力概览
+
+- 自定义块语法：`::tabs`、`::details`、`::ComponentName`
+- 内联组件语法：`:badge[...]()`、`:tip[...]()`
+- 上标 / 下标转换：`sup`、`sub`
+- 特定代码块到组件的转换：`chart`、`mermaid`、`music`
+- 脚注标题修正
+- Markdown 标题提取
+
+## 最常用的接入方式
+
+### 1. 使用预设插件
+
+```ts
+import { createMarkdownPreset } from "@luckyfishes/markdown-core";
+
+const markdownPreset = createMarkdownPreset();
+
+const { remarkPlugins, rehypePlugins } = markdownPreset;
+```
+
+`createMarkdownPreset()` 默认返回：
+
+- `remarkPlugins`
+  - `createCustomSyntaxRemarkPlugin()`
+  - `remark-gfm`
+  - `remarkSuperSub`
+- `rehypePlugins`
+  - `createCodeFenceComponentPlugin()`
+  - `rehypeFootnotesHeading()`
+
+### 2. 在 MDX 渲染链路中使用
+
+适合 `next-mdx-remote`、`@mdx-js/mdx` 一类真正支持 MDX 组件的方案。
+
+```ts
+import {
+  createMarkdownPreset,
+  YAML_PROP_PREFIX,
+} from "@luckyfishes/markdown-core";
+
+const markdownPreset = createMarkdownPreset();
+
+function decodeYamlPropValue(value: unknown): unknown {
+  if (typeof value !== "string" || !value.startsWith(YAML_PROP_PREFIX)) {
+    return value;
+  }
+
+  return JSON.parse(decodeURIComponent(value.slice(YAML_PROP_PREFIX.length)));
+}
+
+function decodeYamlProps<T extends Record<string, unknown>>(props: T): T {
+  return Object.fromEntries(
+    Object.entries(props).map(([key, value]) => [key, decodeYamlPropValue(value)]),
+  ) as T;
+}
+```
+
+说明：
+
+- 自定义块语法里的 YAML 属性，在 AST 中可能会被编码成字符串
+- 运行时渲染组件前，建议使用 `YAML_PROP_PREFIX` 进行一次解码
+- `noname_blog` 就是通过这种方式把数组、对象、布尔值还原回组件 props
+
+### 3. 在 `react-markdown` 中使用
+
+适合“不跑 MDX 编译，只想在 React Markdown 中消费这些语法”的场景。
+
+这时接入方通常需要额外做三件事：
+
+- 在 `remarkRehypeOptions.passThrough` 中保留 `mdxJsxFlowElement` 和 `mdxJsxTextElement`
+- 增加一个 rehype 插件，把 MDX JSX 节点转成普通 HAST 元素
+- 在 `rehype-sanitize` 中放行这些自定义标签和属性
+
+参考思路可以看仓库外的接入项目 `luckywiki`：
+
+- 把 `Badge` 转成 `mdx-badge`
+- 把 `Tabs` 转成 `mdx-tabs`
+- 未识别的块组件转成兜底标签，例如 `mdx-component-block`
+
+## 默认会生成哪些组件
+
+如果调用 `createMarkdownPreset()` 且不传自定义配置，引用本项目的项目至少需要准备这些组件或等价渲染器。
+
+### 自定义内联 / 块组件
+
+来自 `createCustomSyntaxRemarkPlugin()` 的默认命名：
+
+- `Badge`
+- `Tip`
+- `Tabs`
+- `TabsList`
+- `TabsTrigger`
+- `TabsContent`
+
+### 代码块组件
+
+来自 `createCodeFenceComponentPlugin()` 的默认映射：
+
+- ```` ```chart ```` -> `ChartBlock`，属性名 `spec`
+- ```` ```mermaid ```` -> `MermaidDiagram`，属性名 `chart`
+- ```` ```music ```` -> `MusicScore`，属性名 `score`
+
+### 业务块组件
+
+凡是写成下面这种语法的内容：
+
+```md
+::Callout
+title: Example
+---
+Body
+::
+```
+
+都会被转换成同名组件：
+
+- `::Callout` -> `Callout`
+- `::Timeline` -> `Timeline`
+- `::Chat` -> `Chat`
+
+也就是说，**接入方需要自行提供这些业务组件**。这个库不会内置任何实现。
+
+### 原生 HTML 元素
+
+以下内容不会要求你补 React 组件，但你的渲染链路需要能正确处理：
+
+- `::details` -> `details` / `summary`
+- 上标 / 下标 -> `sup` / `sub`
+- 脚注标题 -> `h1` 或 `h2`
+
+## “引用本项目的项目”需要补充什么
+
+如果另一个项目要依赖这个库，通常至少要补齐下面几类内容。
+
+### 1. 组件实现
+
+最低建议清单：
+
+- `Badge`
+- `Tip`
+- `Tabs`
+- `TabsList`
+- `TabsTrigger`
+- `TabsContent`
+- `ChartBlock`
+- `MermaidDiagram`
+- `MusicScore`
+
+如果文档内容里用了额外块组件，还要继续补：
+
+- `Callout`
+- `Timeline`
+- `Chat`
+- `LinkCard`
+- `Icon`
+- `Card`
+- 其他 `::ComponentName` 对应的同名组件
+
+### 2. YAML props 解码
+
+当块组件 props 中包含：
+
+- 布尔值
+- 数组
+- 对象
+- 数字数组等复杂结构
+
+这些值会被编码后挂到 MDX 节点属性上。接入方渲染组件前，需要使用 `YAML_PROP_PREFIX` 做一次解码。
+
+### 3. 渲染框架集成
+
+接入方要自己决定如何把 AST 接到渲染层，例如：
+
+- `next-mdx-remote`
+- `@mdx-js/mdx`
+- `react-markdown`
+- 自己的 unified 管线
+
+### 4. 样式与交互
+
+这个库只产出语义结构，不提供：
+
+- Tabs 的切换逻辑
+- Tip 的复制交互
+- Mermaid / Music 的实际渲染
+- 图表绘制
+- 任何 CSS 样式
+
+这些都需要引用方自己补。
+
+## 支持的语法
+
+### 1. `::tabs`
+
+```md
+::tabs
+tabs:
+  - Overview
+  - Details
+---
+第一屏内容
+---
+第二屏内容
+::
+```
+
+会生成：
+
+- `Tabs`
+- `TabsList`
+- `TabsTrigger`
+- `TabsContent`
+
+### 2. `::details`
+
+```md
+::details [open] Deep Dive
+
+可折叠内容
+
+::
+```
+
+会生成：
+
+- `details`
+- `summary`
+
+### 3. 通用块组件 `::ComponentName`
+
+```md
+::Callout
+title: Example
+count:
+  - 1
+  - 2
+---
+Paragraph content
+::
+```
+
+会生成 `Callout` 组件，并把 YAML 内容作为 props。
+
+### 4. 内联组件
+
+```md
+Hello :badge[Stable](outline)
+Nested :tip[Token](copy)
+```
+
+默认会生成：
+
+- `Badge`
+- `Tip`
+
+其中 `:tip[...]()` 支持的常见参数包括：
+
+- `copy`
+- `tip`
+- `tooltip`
+- `message`
+- `value`
+
+### 5. 特定代码块
+
+````md
+```chart
+{ "type": "pie" }
+```
+````
+
+````md
+```mermaid
+flowchart LR
+A --> B
+```
+````
+
+````md
+```music
+C D E F G
+```
+````
+
+默认分别转换为：
+
+- `ChartBlock`
+- `MermaidDiagram`
+- `MusicScore`
+
+## 自定义配置
+
+### 覆盖自定义组件名
+
+```ts
+import { createMarkdownPreset } from "@luckyfishes/markdown-core";
+
+const preset = createMarkdownPreset({
+  customSyntax: {
+    componentNames: {
+      badge: "Pill",
+    },
+  },
+});
+```
+
+这样 `:badge[New](soft)` 会生成 `Pill` 而不是 `Badge`。
+
+### 覆盖代码块映射
+
+```ts
+import {
+  createMarkdownPreset,
+  DEFAULT_CODE_FENCE_COMPONENT_MAPPINGS,
+} from "@luckyfishes/markdown-core";
+
+const preset = createMarkdownPreset({
+  codeFenceMappings: {
+    ...DEFAULT_CODE_FENCE_COMPONENT_MAPPINGS,
+    mermaid: {
+      componentName: "Diagram",
+      propName: "value",
+    },
+  },
+});
+```
+
+## 标题提取
+
+```ts
+import { extractHeadings } from "@luckyfishes/markdown-core";
+
+const headings = extractHeadings(markdown);
+```
+
+返回值示例：
+
+```ts
+[
+  { depth: 1, text: "Title", id: "title" },
+  { depth: 2, text: "Section", id: "section" },
+]
+```
+
+如果文档里包含脚注，还会自动补一个脚注标题。
+
+## 适合谁用
+
+适合这些场景：
+
+- 你已经有自己的 Markdown/MDX 渲染系统
+- 你想复用一套自定义 Markdown 语法
+- 你愿意自己实现渲染组件、样式和交互
+
+不适合这些场景：
+
+- 你希望安装后开箱即用地渲染完整页面
+- 你不想维护任何自定义组件
+- 你需要一个带 UI 的 Markdown 渲染器
+
+## 导出 API
+
+- `createMarkdownPreset`
+- `createCustomSyntaxRemarkPlugin`
+- `createCodeFenceComponentPlugin`
+- `rehypeFootnotesHeading`
+- `remarkSuperSub`
+- `extractHeadings`
+- `YAML_PROP_PREFIX`
+- `DEFAULT_CUSTOM_SYNTAX_COMPONENT_NAMES`
+- `DEFAULT_CODE_FENCE_COMPONENT_MAPPINGS`
+- `FOOTNOTES_HEADING_ID`
+- `FOOTNOTES_HEADING_TEXT`
+
+## 参考
+
+这个库当前主要在以下项目中被消费：
+
+- `noname_blog`：MDX 编译链路接入，运行时解码 props 并挂载真实 React 组件
+- `luckywiki`：`react-markdown` 链路接入，把 MDX JSX 节点转换成自定义标签后再渲染