markdown-parser

npm install @ferrow/markdown-parser

A focused Markdown metadata extractor for TypeScript/Node.

This is explicitly not a full CommonMark/GFM renderer. It does not produce HTML and does not implement the full CommonMark spec (nested lists, tables, HTML blocks, reference-style links, etc. are out of scope). What it does well: pull structured metadata out of a Markdown document for indexing, documentation tooling, or RAG pipelines. If you need to render Markdown to HTML or need spec-complete parsing, use marked or remark instead.

Install

Copy src/index.ts into your project, or build this repo (npm run build) and depend on the compiled dist/.

Quickstart

import { parse } from 'markdown-parser';

const { frontmatter, toc, codeBlocks, links, summary } = parse(markdownSource);

API

• parse(source: string): ParsedMarkdown
  • frontmatter: Record<string, string> — flat key/value pairs from a leading ----delimited block (simple key: value lines only — not full YAML: no nested objects, lists, or multi-line values).
  • toc: HeadingNode[] — a heading tree built from ATX #..###### headings, nested by depth. Each node is { depth, text, slug, children }; duplicate headings get suffixed slugs (installation, installation-1, ...).
  • codeBlocks: { lang: string | null; content: string }[] — every fenced (```) code block in source order, with its language tag if present.
  • links: { text: string; url: string }[] — inline [text](url) links. Reference-style links ([text][ref]) are not extracted.
  • summary: string — the document body with frontmatter, code fences, and inline formatting (bold/italic/code/links/list markers) stripped down to plain text.
• slugify(text: string): string — GitHub-style slug (lowercase, spaces to hyphens, non-word characters stripped). Used internally for toc.

Scope and limits

• ATX headings only (# Heading) — Setext-style (Heading\n===) is not recognized.
• Frontmatter parsing is intentionally simple: one key: value per line, optional quotes stripped. No nested structures.
• Links are inline-style only; reference-style [text][ref] + [ref]: url definitions are not extracted.
• summary strips formatting but does not handle every CommonMark construct (e.g. tables, HTML blocks) — it's meant for a rough plain-text preview, not a faithful text rendering.

Sponsored by Ferrow

---

Part of the ferrow-toolkit collection · Sponsored by Ferrow