remark

remark is a markdown processor built on the unified collective. It parses markdown into a structured mdast syntax tree, lets a pipeline of plugins inspect and transform that tree, and serializes it back to markdown. The core remark package is a thin, frozen preset that wires remark-parse and remark-stringify onto a unified processor, so you get a ready-to-use markdown-in, markdown-out pipeline.

Because everything flows through the shared unist/mdast tree, remark powers everything from linting and formatting to content migrations and static-site generation. Its plugin ecosystem is one of the largest in the JavaScript world, covering GitHub Flavored Markdown, frontmatter, MDX, syntax tooling, and more.

What You Get

• A ready-to-use markdown processor exposing the single remark() factory that returns a frozen unified processor.
• Access to the mdast (markdown AST) representation for programmatic inspection and transformation of documents.
• A vast plugin ecosystem for GFM, frontmatter, MDX, linting, formatting, and custom transforms.
• First-class TypeScript types and ESM support with 100% type coverage enforced in CI.

Common Use Cases

• Programmatically formatting and normalizing markdown files across a repository or docs site.
• Linting markdown for style and consistency as part of a CI pipeline or editor integration.
• Transforming markdown content during static-site or content-pipeline builds.
• Converting between markdown flavors or extracting structured data from markdown documents.

Under The Hood

Architecture remark’s core package (packages/remark/index.js) is deliberately tiny: it imports remark-parse and remark-stringify, chains them onto a unified() processor with .use(...).use(...), and calls .freeze() to lock the preset. All real work happens in the unified ecosystem — remark-parse turns markdown text into an mdast tree via micromark, plugins registered by consumers walk and mutate that tree, and remark-stringify serializes the tree back to markdown. This tree-in-the-middle design is what lets an entire plugin ecosystem interoperate on a single shared data structure (mdast/unist).

Tech Stack The library is pure ESM JavaScript with hand-written TypeScript declarations (index.d.ts). Its runtime dependencies are unified, remark-parse, remark-stringify, and @types/mdast. The monorepo is a pnpm/npm workspace containing remark, remark-parse, remark-stringify, and remark-cli. Tooling includes TypeScript for type-checking and declaration builds, xo + prettier for linting/formatting, and c8 for coverage.

Code Quality Quality standards are unusually high: the project enforces typeCoverage.atLeast: 100 in strict mode, runs xo and prettier, and gates on c8 --100 coverage. Tests live in a 355-line test.js using Node’s built-in node:test runner and assert/strict, exercising the public API surface, settings handling, and the CLI end to end. The public surface of the core package is a single named export, keeping the maintenance burden minimal.

API Design The developer experience is excellent for its scope: remark() returns a standard unified processor, so the API is remark().use(plugin).process(file) with sync (processSync) and async variants. Naming is consistent with the wider unified/remark ecosystem, documentation is extensive (a thorough readme plus getting-started, plugins, and products guides), and getting started requires almost no boilerplate. The main conceptual cost is learning the unified processor model and the mdast tree, which the docs address directly.