Zero-dependency, TypeScript-typed RegExp patterns for extracting headers, links, images, lists and code from Markdown.
Install (30 seconds):
npm install markdown-regeximport { extractLinks, extractHeaders } from 'markdown-regex';
extractLinks('[docs](https://example.com)');
// [{ text: 'docs', url: 'https://example.com' }]
extractHeaders('# Hello\n## World');
// [{ level: 1, text: 'Hello' }, { level: 2, text: 'World' }]Requires Node.js 20+. CI builds on Node 20, 22, and 24.
- Agent guide: AGENTS.md
- Full API: llms-full.txt · Short: llms.txt
- Source index: src/index.ts
Use markdown-regex for quick extraction, linting, or lightweight transforms — especially in scripts and AI-agent tool calls that want JSON, not an AST.
Do not use it when you need an AST or CommonMark compliance. Use remark, micromark, or markdown-it.
| Channel | Version | Notes |
|---|---|---|
npm latest |
2.1.1 | TypeScript, ESM + CJS, provenance-signed |
GitHub main |
2.1.x | Same line as npm |
| Package name | markdown-regex |
Same name on GitHub and npm |
npm install markdown-regeximport { extractLinks, extractHeaders, REGEXP_LINK } from 'markdown-regex';
extractLinks('[a](b)');
// [{ text: 'a', url: 'b' }]
extractHeaders('# Title');
// [{ level: 1, text: 'Title' }]
'[a](b)'.match(REGEXP_LINK);
// ['[a](b)', 'a', 'b']Every regex is global (g). Reset .lastIndex between .test() calls, or use matchAll.
See the tables in this README and llms-full.txt. HTML cleanup lives on markdown-regex/cleanup.
import { REGEXP_EMPTY_UL } from 'markdown-regex/cleanup';
import { extractLinks } from 'markdown-regex';| Library | Job | Deps | Typed extract helpers | When to pick it |
|---|---|---|---|---|
| markdown-regex (this) | RegExp constants + extract* |
0 | Yes (links / headers / images / full extract) |
Lint, scripts, AI-agent tools, cheap transforms |
| markdown-link-extractor | Links only | small | Links | You only need URLs from Markdown |
| remove-markdown | Strip markup → plain text | 0 | No | Plain-text previews / search indexing |
| extract-md-headings | Headings only | small | Headings | TOC-like heading lists |
| remark / micromark / markdown-it | Full parse / AST | ecosystem | Via AST | Spec compliance, rendering, complex transforms |
markdown-regex is not a CommonMark parser. Prefer remark/micromark/markdown-it when you need an AST.
pnpm workspaces + Turborepo. Private packages @markdown-regex/core, frontmatter, blocks, and email are bundled into the public markdown-regex package. Subpath imports:
import { extract } from 'markdown-regex';
import { parseFrontmatter } from 'markdown-regex/frontmatter'; // see docs/frontmatter.md
import { extractCustomBlocks } from 'markdown-regex/blocks';
import { prepareForEmail } from 'markdown-regex/email';
import { REGEXP_EMPTY_UL } from 'markdown-regex/cleanup';RegExp literals live in src/patterns/ (block / inline / cleanup). Legacy folders under src/tags/, src/lists/, src/code/, and src/html/ only re-export those constants so older relative imports keep working.
dist/ is generated by npm run build and is gitignored — do not commit built artifacts.
- Nested emphasis is not fully handled.
REGEXP_LINKon raw Markdown matches inside code. UseextractLinks().- Reference links and setext headers are not matched.
- See SECURITY.md for ReDoS. CI runs
tests/redos.test.tson every exported pattern.
Copy-paste samples under examples/recipes/:
- Links → JSON:
examples/recipes/links-only.mjs - Header TOC:
examples/recipes/toc-headers.mjs - Code-aware vs raw regex:
examples/recipes/strip-code-then-match.mjs
npx markdown-regex links README.md
npx markdown-regex headers doc.md
npx markdown-regex images doc.md
npx markdown-regex extract doc.md
cat doc.md | npx markdown-regex linksPrints JSON. No extra runtime dependencies.
npm install
npm run build
npm run typecheck
npm test
npm run test:coverageTests are Vitest (tests/**/*.test.ts). Jest is not used.
CI builds on Node 20, 22, and 24.
Scaffold: docs/ (Docusaurus via documentation-actions coming next).
Example tool shape (JSON in, JSON out): examples/mcp-tool-shape.ts.
Also see AGENTS.md and llms.txt.
- NPM: https://www.npmjs.com/package/markdown-regex
- Used by: https://github.com/LLazyEmail/markdown-to-email
- Article: https://hackernoon.com/open-sourcing-regular-expressions-for-markdown-syntax-module
- Agent guide: https://github.com/LLazyEmail/markdown-regex/blob/main/AGENTS.md
- Full API: https://github.com/LLazyEmail/markdown-regex/blob/main/llms-full.txt
- Source index: https://github.com/LLazyEmail/markdown-regex/blob/main/src/index.ts
MIT
Full-document snapshot tests live under fixtures/real-world/. Run them with:
pnpm test:fixtures # assert
pnpm test:fixtures:update # update snapshotsSee fixtures/README.md. CI runs these in a separate Fixtures workflow (PRs + nightly).