How remarkjs/remark-rehype works
Project type and purpose
• This is an open-source Node.js library (an ESM-only “unified” plugin) called remark-rehype.
• Its sole responsibility is to transform a Markdown syntax tree (mdast) into an HTML syntax tree (hast) so that downstream rehype (HTML) plugins can operate on it.
• It is not a full-stack application or microservice, but rather a bridge in a compiler-like processing pipeline.
File structure analysis
• Top-level files
• index.js — module entry point that re-exports or wraps the code in lib/index.js
• lib/index.js — main implementation of the remark-rehype transformer
• test.js — example or test runner
• package.json — metadata, dependencies, exports field pointing to index.js
• tsconfig.json — TypeScript configuration for type checking
• .github/workflows — CI definitions (build, test)
• .gitignore, .editorconfig, .prettierignore, .npmrc, license, readme.md
• No separate frontend/backend concerns—this is a library with one core component (the transformer).
Key architectural insights from README
• remark-rehype plugs into a unified pipeline:
[unified engine] → remark-parse → mdast → remark-rehype → hast → rehype-* plugins → rehype-stringify → HTML
• It supports two modes: bridge mode (passing through to another processor) and mutate mode (returning hast).
• It exports a transformer function plus helper functions (defaultFootnoteBackContent, defaultHandlers, etc.).
• It allows user customization via options (handlers, unknownHandler, footnote settings, allowDangerousHtml).
Main components
A. Unified processing engine
• Represents the central orchestrator that runs the pipeline.
B. remark-parse
• Takes raw Markdown text → produces mdast (Markdown AST).
C. remark-rehype
• Accepts mdast → transforms to hast (HTML AST).
• Core logic lives in lib/index.js.
• Exposes configuration options and handlers.
D. mdast-util-to-hast (optional subcomponent)
• Underlying utility invoked by remark-rehype to do the node-by-node conversion.
E. rehype plugins (post-bridge)
• Examples: rehype-document, rehype-format, rehype-sanitize, rehype-stringify.
• Operate on hast to modify or serialize it.
F. Output layer
• rehype-stringify (if used) serializes hast → HTML text.
G. External services / integrations
• File system (to-vfile) for reading/writing files.
• npm registry for distribution.
• CI pipelines for testing and publishing.
Relationships and data flow
1. Markdown file (input)
→ unified().use(remarkParse)
2. mdast tree
→ unified().use(remarkRehype, options)
3. hast tree
→ .use(rehypeRaw? → rehypeSanitize? → other rehype plugins…)
4. .use(rehypeStringify)
5. HTML string (output)
• Option injection into remark-rehype (handlers, footnote settings, allowDangerousHtml).
Architectural patterns and design principles
• Plugin-based pipeline (chain of responsibility).
• Separation of concerns: parsing → AST conversion → HTML transformation → serialization.
• Extensibility via user-provided handlers and passThrough lists.
• Immutable data flow (each plugin receives and returns a tree).