{"id":11287,"library":"mdast-util-from-markdown","title":"Markdown to mdast AST Parser","description":"mdast-util-from-markdown is a foundational utility in the syntax-tree ecosystem, designed to parse Markdown input into an mdast (Markdown Abstract Syntax Tree) syntax tree. It leverages the micromark tokenizer internally and transforms its output into a tree structure. The current stable version is 2.0.3, with frequent patch and minor releases, while major versions like 2.0.0 introduce significant breaking changes such as the shift to ESM-only and a minimum Node.js 16 requirement. This package provides a lower-level API for direct AST manipulation, making it suitable for developers who need fine-grained control over the parsing process or wish to integrate custom syntax extensions like GFM, MDX, Math, or Frontmatter. It is distinct from micromark (which focuses on direct HTML output) and remark-parse (which offers a higher-level, more abstracted content processing experience within the remark ecosystem).","status":"active","version":"2.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/mdast-util-from-markdown","tags":["javascript","ast","markdown","markup","mdast-util","mdast","parse","syntax","tree","typescript"],"install":[{"cmd":"npm install mdast-util-from-markdown","lang":"bash","label":"npm"},{"cmd":"yarn add mdast-util-from-markdown","lang":"bash","label":"yarn"},{"cmd":"pnpm add mdast-util-from-markdown","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core internal dependency for tokenization; major version updates in micromark often necessitate breaking changes in mdast-util-from-markdown.","package":"micromark","optional":false}],"imports":[{"note":"mdast-util-from-markdown has been ESM-only since v2.0.0, requiring Node.js 16+. CommonJS `require` is not supported for direct imports.","wrong":"const fromMarkdown = require('mdast-util-from-markdown')","symbol":"fromMarkdown","correct":"import { fromMarkdown } from 'mdast-util-from-markdown'"},{"note":"This symbol represents a TypeScript type definition for extending Markdown parsing, not a runtime value. It should be imported as a type.","wrong":"import { Extension } from 'mdast-util-from-markdown'","symbol":"Extension","correct":"import type { Extension } from 'mdast-util-from-markdown'"},{"note":"This symbol represents a TypeScript type definition for the parser configuration, not a runtime value. It should be imported as a type.","wrong":"import { Options } from 'mdast-util-from-markdown'","symbol":"Options","correct":"import type { Options } from 'mdast-util-from-markdown'"}],"quickstart":{"code":"import fs from 'node:fs/promises'\nimport {fromMarkdown} from 'mdast-util-from-markdown'\n\nasync function parseExample() {\n  // Assume 'example.md' contains '## Hello, *World*!'\n  const doc = await fs.readFile('example.md', 'utf8')\n  const tree = fromMarkdown(doc)\n\n  console.log(JSON.stringify(tree, null, 2))\n  // Expected output:\n  // {\n  //   \"type\": \"root\",\n  //   \"children\": [\n  //     {\n  //       \"type\": \"heading\",\n  //       \"depth\": 2,\n  //       \"children\": [\n  //         { \"type\": \"text\", \"value\": \"Hello, \" },\n  //         { \"type\": \"emphasis\", \"children\": [{ \"type\": \"text\", \"value\": \"World\" }] },\n  //         { \"type\": \"text\", \"value\": \"!\" }\n  //       ]\n  //     }\n  //   ]\n  // }\n}\n\nparseExample().catch(console.error)","lang":"javascript","description":"This quickstart demonstrates how to asynchronously read a Markdown file and parse its content into an mdast syntax tree using the `fromMarkdown` utility."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or newer. Use nvm or your preferred Node.js version manager.","message":"Version 2.0.0 of `mdast-util-from-markdown` requires Node.js version 16 or higher. Older Node.js versions are no longer supported.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Migrate your codebase to use ES module `import` syntax. Ensure your `package.json` specifies `\"type\": \"module\"` or use `.mjs` file extensions. For mixed CJS/ESM projects, consider dynamic `import()`.","message":"The package became ESM-only (ECMAScript Modules) in version 2.0.0. CommonJS `require()` statements are no longer supported for direct imports.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"If you are passing raw buffers, ensure they are converted to `Uint8Array` instances before passing them to `fromMarkdown`. For example, `new Uint8Array(myBuffer)`.","message":"Version 2.0.0 updated its internal `micromark` dependency to v4, which changed how buffers are handled. Input values or encodings that previously accepted Node.js `Buffer` objects now expect `Uint8Array`s.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"If you have custom markdown extensions that interact deeply with `mdast-util-from-markdown`'s internals, you will need to update them according to the `micromark@4` and `mdast-util-from-markdown@2` migration guides. Review `Extension` and `CompileContext` types for changes.","message":"The internal API for creating custom extensions changed significantly in v2.0.0, specifically replacing getter/setters for some properties with direct assignments.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Choose the right tool for the job: `micromark` for direct HTML, `remark` for plugin-based content transformation, `mdast-util-from-markdown` for direct AST manipulation.","message":"This utility is for building an mdast syntax tree. If your goal is simply to convert Markdown to HTML, `micromark` is a more direct choice. If you want a higher-level content processing pipeline, consider the `remark` ecosystem and `remark-parse`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Update your import statements to use `import { fromMarkdown } from 'mdast-util-from-markdown'` and ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`).","cause":"Attempting to use CommonJS `require()` in an environment that expects ES Modules.","error":"ReferenceError: require is not defined"},{"fix":"Convert your `Buffer` instances to `Uint8Array` before passing them. Example: `fromMarkdown(new Uint8Array(myBuffer))`.","cause":"Passing a Node.js `Buffer` object to `fromMarkdown` for the `value` or `encoding` argument after upgrading to v2.x, which expects `Uint8Array`.","error":"TypeError: Expected Uint8Array, got Buffer"},{"fix":"Upgrade your Node.js version to 16 or newer. Also, verify your project's `package.json` correctly specifies `\"type\": \"module\"` if you're using explicit ESM in your files.","cause":"Using an outdated Node.js version (prior to 16) with `mdast-util-from-markdown` v2.x, which is ESM-only and requires Node.js 16+.","error":"Error: Cannot find package 'mdast-util-from-markdown' imported from ..."},{"fix":"Ensure you are using a named import: `import { fromMarkdown } from 'mdast-util-from-markdown'`. The package has no default export.","cause":"Incorrectly attempting to use a default import for `fromMarkdown`, or a typo in the named import.","error":"TypeError: fromMarkdown is not a function"}],"ecosystem":"npm"}