Developer Reference

给集成 @rho/md 库到自己产品的开发者：API、build-time pipeline、runtime hydration、CSS 主题化、nested DSL inner processor、自己实现 reader 的指南。

写 .md 内容的写作者请去 Writer's Guide。

@rho/md 是什么

@rho/md 是 Rho format 的参考实现——一个 npm 库，由 scos-lab 维护。

它干两件事：

1. build-time：把 .md 源（含 Rho DSL）解析 + 转换 → HTML
2. runtime：在 HTML 渲染后 hydrate 交互块（slider / chart / 动画）

集成它，你的 reader / 网站 / app 立刻支持 Rho format 的全部 15 capability——不用从零实现 spec。

状态——尚未上 npm：stl-md 和 @rho/md 今天在 npm registry 上都解析不到，所以本节里的 npm install 与 CDN 行描述的是计划中的包，现在照着跑会失败。本节作为包发布之后的前瞻参考保留。

三种集成场景

场景 A：自建网站 / 博客 / docs 站

最常见。你有一个 React / Vue / Astro / VitePress 项目，想在某些页面渲染 .md 文件并支持 Rho。

→ Quick start (unified pipeline) → Hydration utilities

场景 B：自己的 markdown reader / 编辑器

你做了个 markdown 工具（类似 Obsidian / Typora），想加 Rho 支持。

→ Quick start → Inner processor (nested DSL) → Implementing your own reader（如果想从 spec 自实现而不用 @rho/md）

场景 C：服务端 SSR

你在 Node.js / Cloudflare Worker / Next.js SSR 里渲染 markdown。

→ Install → Quick start → Hydration 需要在客户端（SSR 渲染 HTML，浏览器调 hydrateAll）

核心架构

你的 .md 源
    │
    │ Build time (Node / Astro / Vite / etc.)
    ▼
┌─────────────────────────────────────┐
│  unified pipeline                   │
│   ├── remarkParse                   │
│   ├── remarkGfm                     │
│   ├── @rho/md remarkPlugins (×7)    │  ← Rho 把 callout / layout / interact 等
│   │     ├── remarkCallout           │     转成 HTML AST
│   │     ├── remarkLayout            │
│   │     ├── remarkAnnotate          │
│   │     ├── remarkTabs              │
│   │     ├── remarkStepper           │
│   │     ├── remarkTimeline          │
│   │     └── remarkModal             │
│   ├── remarkRehype                  │
│   └── rehypeStringify               │
└─────────────────────────────────────┘
    │
    ▼
HTML 字符串 (含 Rho marker classes)
    │
    │ Insert into DOM
    ▼
┌─────────────────────────────────────┐
│  Browser runtime                    │
│   └── hydrateAll(container)         │  ← Rho 扫 marker class 把静态 HTML
│         ├── renderInteractBlocks    │     变成可交互组件
│         ├── renderTabsBlocks        │
│         ├── renderStepperBlocks     │
│         └── renderModalBlocks       │
└─────────────────────────────────────┘
    │
    ▼
完全可交互 Rho 渲染

关键概念：

• Build-time 部分跑在 Node 或 build pipeline 里（不需要浏览器）
• Runtime 部分（hydration）必须在浏览器
• 所有 Rho DSL 都在 build-time 转成"标记好的 HTML"，hydration 时按 marker 接管

API 速览

import {
  // build-time
  remarkPlugins,            // 7 remark plugin 数组
  remarkCallout,            // 单独引用
  remarkLayout,
  remarkAnnotate,
  remarkTabs,
  remarkStepper,
  remarkTimeline,
  remarkModal,

  // nested DSL 支持
  registerInnerPlugin,      // 单个注册
  registerAllInnerPlugins,  // 一键全注册
  parseInner,               // 解析嵌套内容

  // runtime hydration
  hydrateAll,               // 一键 hydrate 全部
  renderInteractBlocks,     // 单独 hydrate interact
  renderTabsBlocks,
  renderStepperBlocks,
  renderModalBlocks,

  // STL syntax highlighting
  stlLanguage,              // highlight.js / lowlight grammar
} from '@rho/md';

import '@rho/md/css';        // 内置 CSS

详见 API reference.

依赖

必须

• unified + remark-parse + remark-gfm + remark-rehype + rehype-stringify——markdown pipeline 标配

可选

• vega-embed——用 Interact + Vega-Lite chart 时
• highlight.js / lowlight——用 STL syntax highlighting 时

License

@rho/md 是 PolyForm Noncommercial License 1.0.0：

• ✅ 个人 / 学术 / 非营利 / 评估 → 免费
• ❌ for-profit 公司商用 → 需 commercial license

详见 License.

Spec 本身是 CC BY 4.0 —— 你可以不用 @rho/md 而从 spec 自实现 reader（自实现的话 spec free，你的实现可以选任何 license）。详见 Implementing your own reader.

路径

See also

• Writer's Guide — 给写 .md 的人
• Rho AI / LLM Guide — 给做 AI 集成的人
• License & Commercial — 商业 license 询价
• GitHub: scos-lab/markview（仓库后续 rename 为 scos-lab/rho）
• npm: stl-md（包名后续 rename 为 @rho/md）