Developer Reference

For developers integrating @rho/md into their own product: API, build-time pipeline, runtime hydration, CSS theming, nested-DSL inner processor, guide for implementing your own reader.

Writers of .md content should go to Writer's Guide.

What is @rho/md

@rho/md is the reference implementation of Rho format — an npm library maintained by scos-lab.

It does two things:

1. Build-time: parse + transform .md source (with Rho DSLs) → HTML
2. Runtime: after HTML is rendered, hydrate the interactive blocks (sliders / charts / animations)

Integrate it, and your reader / website / app immediately supports all 15 Rho format capabilities — you don't have to implement the spec from scratch.

Status — not on npm yet: neither stl-md nor @rho/md resolves on the npm registry today, so the npm install and CDN lines in this section describe the planned package and will fail if you run them now. This section is kept as the forward-looking reference for when the package ships.

Three integration scenarios

Scenario A: your own website / blog / docs site

Most common. You have a React / Vue / Astro / VitePress project and want to render .md files with Rho support on certain pages.

→ Quick start (unified pipeline) → Hydration utilities

Scenario B: your own markdown reader / editor

You built a markdown tool (similar to Obsidian / Typora) and want to add Rho support.

→ Quick start → Inner processor (nested DSL) → Implementing your own reader (if you want to implement from spec rather than use @rho/md)

Scenario C: server-side SSR

You render markdown in Node.js / Cloudflare Worker / Next.js SSR.

→ Install → Quick start → Hydration must happen client-side (SSR renders HTML; browser calls hydrateAll)

Core architecture

Your .md source
    │
    │ Build time (Node / Astro / Vite / etc.)
    ▼
┌─────────────────────────────────────┐
│  unified pipeline                   │
│   ├── remarkParse                   │
│   ├── remarkGfm                     │
│   ├── @rho/md remarkPlugins (×7)    │  ← Rho turns callout / layout / interact
│   │     ├── remarkCallout           │     into HTML AST
│   │     ├── remarkLayout            │
│   │     ├── remarkAnnotate          │
│   │     ├── remarkTabs              │
│   │     ├── remarkStepper           │
│   │     ├── remarkTimeline          │
│   │     └── remarkModal             │
│   ├── remarkRehype                  │
│   └── rehypeStringify               │
└─────────────────────────────────────┘
    │
    ▼
HTML string (with Rho marker classes)
    │
    │ Insert into DOM
    ▼
┌─────────────────────────────────────┐
│  Browser runtime                    │
│   └── hydrateAll(container)         │  ← Rho scans marker classes; turns
│         ├── renderInteractBlocks    │     static HTML into interactive components
│         ├── renderTabsBlocks        │
│         ├── renderStepperBlocks     │
│         └── renderModalBlocks       │
└─────────────────────────────────────┘
    │
    ▼
Fully interactive Rho rendering

Key concepts:

• Build-time runs in Node or your build pipeline (no browser needed)
• Runtime (hydration) must run in the browser
• All Rho DSLs are converted at build-time into "marked HTML"; hydration takes over via the markers

API at a glance

import {
  // build-time
  remarkPlugins,            // array of 7 remark plugins
  remarkCallout,            // individually
  remarkLayout,
  remarkAnnotate,
  remarkTabs,
  remarkStepper,
  remarkTimeline,
  remarkModal,

  // nested DSL support
  registerInnerPlugin,      // register one
  registerAllInnerPlugins,  // register all at once
  parseInner,               // parse nested content

  // runtime hydration
  hydrateAll,               // hydrate everything
  renderInteractBlocks,     // hydrate interact only
  renderTabsBlocks,
  renderStepperBlocks,
  renderModalBlocks,

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

import '@rho/md/css';        // built-in CSS

See API reference.

Dependencies

Required

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

Optional

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

License

@rho/md is PolyForm Noncommercial License 1.0.0:

• ✅ Personal / academic / non-profit / evaluation → free
• ❌ For-profit commercial use → requires commercial license

See License.

The spec itself is CC BY 4.0 — you can avoid @rho/md and implement a reader from the spec yourself (the spec is free; your implementation can choose any license). See Implementing your own reader.

Paths

See also

• Writer's Guide — For writers of .md
• Rho AI / LLM Guide — For AI integrators
• License & Commercial — Commercial licensing inquiries
• GitHub: scos-lab/markview (repo to be renamed to scos-lab/rho)
• npm: stl-md (package to be renamed to @rho/md)