{"id":24113694,"url":"https://github.com/syntax-tree/mdast-util-from-markdown","last_synced_at":"2025-05-14T08:05:55.087Z","repository":{"id":42628100,"uuid":"291763905","full_name":"syntax-tree/mdast-util-from-markdown","owner":"syntax-tree","description":"mdast utility to parse markdown","archived":false,"fork":false,"pushed_at":"2025-03-05T11:26:30.000Z","size":272,"stargazers_count":244,"open_issues_count":1,"forks_count":21,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-05-03T07:14:43.140Z","etag":null,"topics":["markdown","mdast","mdast-util","parse","tokenize","unist"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/syntax-tree.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"unifiedjs","open_collective":"unified","thanks_dev":"u/gh/syntax-tree"}},"created_at":"2020-08-31T16:13:21.000Z","updated_at":"2025-04-30T03:23:25.000Z","dependencies_parsed_at":"2023-02-15T11:10:49.303Z","dependency_job_id":"184d47b2-8efd-4a7d-8c06-ecc501fb131d","html_url":"https://github.com/syntax-tree/mdast-util-from-markdown","commit_stats":{"total_commits":158,"total_committers":3,"mean_commits":"52.666666666666664","dds":"0.012658227848101222","last_synced_commit":"5f537c628bba1bb419057de13205d304ad44abbd"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syntax-tree%2Fmdast-util-from-markdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syntax-tree%2Fmdast-util-from-markdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syntax-tree%2Fmdast-util-from-markdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syntax-tree%2Fmdast-util-from-markdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/syntax-tree","download_url":"https://codeload.github.com/syntax-tree/mdast-util-from-markdown/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254076862,"owners_count":22010613,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["markdown","mdast","mdast-util","parse","tokenize","unist"],"created_at":"2025-01-11T04:24:31.277Z","updated_at":"2025-05-14T08:05:50.076Z","avatar_url":"https://github.com/syntax-tree.png","language":"JavaScript","readme":"# mdast-util-from-markdown\n\n[![Build][badge-build-image]][badge-build-url]\n[![Coverage][badge-coverage-image]][badge-coverage-url]\n[![Downloads][badge-downloads-image]][badge-downloads-url]\n[![Size][badge-size-image]][badge-size-url]\n\n**[mdast][github-mdast]** utility that turns markdown into a syntax tree.\n\n## Contents\n\n* [What is this?](#what-is-this)\n* [When should I use this?](#when-should-i-use-this)\n* [Install](#install)\n* [Use](#use)\n* [API](#api)\n  * [`fromMarkdown(value[, encoding][, options])`](#frommarkdownvalue-encoding-options)\n  * [`CompileContext`](#compilecontext)\n  * [`CompileData`](#compiledata)\n  * [`Encoding`](#encoding)\n  * [`Extension`](#extension)\n  * [`Handle`](#handle)\n  * [`OnEnterError`](#onentererror)\n  * [`OnExitError`](#onexiterror)\n  * [`Options`](#options)\n  * [`Token`](#token)\n  * [`Transform`](#transform)\n  * [`Value`](#value)\n* [List of extensions](#list-of-extensions)\n* [Syntax](#syntax)\n* [Syntax tree](#syntax-tree)\n* [Types](#types)\n* [Compatibility](#compatibility)\n* [Security](#security)\n* [Related](#related)\n* [Contribute](#contribute)\n* [License](#license)\n\n## What is this?\n\nThis package is a utility that takes markdown input and turns it into an\n[mdast][github-mdast] syntax tree.\n\nThis utility uses [`micromark`][github-micromark],\nwhich turns markdown into tokens,\nand then turns those tokens into nodes.\nThis package is used inside [`remark-parse`][github-remark-parse],\nwhich focusses on\nmaking it easier to transform content by abstracting these internals away.\n\n## When should I use this?\n\nIf you want to handle syntax trees manually, use this.\nWhen you *just* want to turn markdown into HTML,\nuse [`micromark`][github-micromark] instead.\nFor an easier time processing content,\nuse the **[remark][github-remark]** ecosystem instead.\n\nYou can combine this package with other packages to add syntax extensions to\nmarkdown.\nNotable examples that deeply integrate with this package are\n[`mdast-util-mdx`][github-mdast-util-mdx],\n[`mdast-util-gfm`][github-mdast-util-gfm],\n[`mdast-util-frontmatter`][github-mdast-util-frontmatter],\n[`mdast-util-math`][github-mdast-util-math], and\n[`mdast-util-directive`][github-mdast-util-directive].\n\n## Install\n\nThis package is [ESM only][github-gist-esm].\nIn Node.js (version 16+), install with [npm][npmjs-install]:\n\n```sh\nnpm install mdast-util-from-markdown\n```\n\nIn Deno with [`esm.sh`][esmsh]:\n\n```js\nimport {fromMarkdown} from 'https://esm.sh/mdast-util-from-markdown@2'\n```\n\nIn browsers with [`esm.sh`][esmsh]:\n\n```html\n\u003cscript type=\"module\"\u003e\n  import {fromMarkdown} from 'https://esm.sh/mdast-util-from-markdown@2?bundle'\n\u003c/script\u003e\n```\n\n## Use\n\nSay we have the following markdown file `example.md`:\n\n```markdown\n## Hello, *World*!\n```\n\n…and our module `example.js` looks as follows:\n\n```js\nimport fs from 'node:fs/promises'\nimport {fromMarkdown} from 'mdast-util-from-markdown'\n\nconst doc = await fs.readFile('example.md')\nconst tree = fromMarkdown(doc)\n\nconsole.log(tree)\n```\n\n…now running `node example.js` yields (positional info removed for brevity):\n\n```js\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\n## API\n\nThis package exports the identifier [`fromMarkdown`][api-from-markdown].\nThere is no default export.\n\nThe export map supports the [`development` condition][node-packages-conditions].\nRun `node --conditions development example.js` to get instrumented dev code.\nWithout this condition, production code is loaded.\n\n### `fromMarkdown(value[, encoding][, options])`\n\nTurn markdown into a syntax tree.\n\n###### Overloads\n\n* `(value: Value, encoding: Encoding, options?: Options) =\u003e Root`\n* `(value: Value, options?: Options) =\u003e Root`\n\n###### Parameters\n\n* `value` ([`Value`][api-value])\n  — markdown to parse\n* `encoding` ([`Encoding`][api-encoding], default: `'utf8'`)\n  — [character encoding][node-util-encoding] for when `value` is\n  [`Uint8Array`][mozilla-uint8-array]\n* `options` ([`Options`][api-options], optional)\n  — configuration\n\n###### Returns\n\nmdast tree ([`Root`][github-mdast-root]).\n\n### `CompileContext`\n\nmdast compiler context (TypeScript type).\n\n###### Fields\n\n* `stack` ([`Array\u003cNode\u003e`][github-mdast-nodes])\n  — stack of nodes\n* `tokenStack` (`Array\u003c[Token, OnEnterError | undefined]\u003e`)\n  — stack of tokens\n* `data` ([`CompileData`][api-compile-data])\n  — info passed around; key/value store\n* `buffer` (`() =\u003e undefined`)\n  — capture some of the output data\n* `resume` (`() =\u003e string`)\n  — stop capturing and access the output data\n* `enter` (`(node: Node, token: Token, onError?: OnEnterError) =\u003e undefined`)\n  — enter a node\n* `exit` (`(token: Token, onError?: OnExitError) =\u003e undefined`)\n  — exit a node\n* `sliceSerialize` (`(token: Token, expandTabs?: boolean) =\u003e string`)\n  — get the string value of a token\n* `config` (`Required\u003cExtension\u003e`)\n  — configuration\n\n### `CompileData`\n\nInterface of tracked data (TypeScript type).\n\n###### Type\n\n```ts\ninterface CompileData { /* see code */ }\n```\n\nWhen working on extensions that use more data, extend the corresponding\ninterface to register their types:\n\n```ts\ndeclare module 'mdast-util-from-markdown' {\n  interface CompileData {\n    // Register a new field.\n    mathFlowInside?: boolean | undefined\n  }\n}\n```\n\n### `Encoding`\n\nEncodings supported by the [`Uint8Array`][mozilla-uint8-array] class\n(TypeScript type).\n\nSee [`micromark`][github-micromark-api] for more info.\n\n###### Type\n\n```ts\ntype Encoding = 'utf8' | /* … */\n```\n\n### `Extension`\n\nChange how markdown tokens from micromark are turned into mdast (TypeScript\ntype).\n\n###### Properties\n\n* `canContainEols` (`Array\u003cstring\u003e`, optional)\n  — token types where line endings are used\n* `enter` ([`Record\u003cstring, Handle\u003e`][api-handle], optional)\n  — opening handles\n* `exit` ([`Record\u003cstring, Handle\u003e`][api-handle], optional)\n  — closing handles\n* `transforms` ([`Array\u003cTransform\u003e`][api-transform], optional)\n  — tree transforms\n\n### `Handle`\n\nHandle a token (TypeScript type).\n\n###### Parameters\n\n* `this` ([`CompileContext`][api-compile-context])\n  — context\n* `token` ([`Token`][api-token])\n  — current token\n\n###### Returns\n\nNothing (`undefined`).\n\n### `OnEnterError`\n\nHandle the case where the `right` token is open, but it is closed (by the\n`left` token) or because we reached the end of the document (TypeScript type).\n\n###### Parameters\n\n* `this` ([`CompileContext`][api-compile-context])\n  — context\n* `left` ([`Token`][api-token] or `undefined`)\n  — left token\n* `right` ([`Token`][api-token])\n  — right token\n\n###### Returns\n\nNothing (`undefined`).\n\n### `OnExitError`\n\nHandle the case where the `right` token is open but it is closed by\nexiting the `left` token (TypeScript type).\n\n###### Parameters\n\n* `this` ([`CompileContext`][api-compile-context])\n  — context\n* `left` ([`Token`][api-token])\n  — left token\n* `right` ([`Token`][api-token])\n  — right token\n\n###### Returns\n\nNothing (`undefined`).\n\n### `Options`\n\nConfiguration (TypeScript type).\n\n###### Properties\n\n* `extensions`\n  ([`Array\u003cMicromarkExtension\u003e`][github-micromark-extension], optional)\n  — micromark extensions to change how markdown is parsed\n* `mdastExtensions`\n  ([`Array\u003cExtension | Array\u003cExtension\u003e\u003e`][api-extension],\n  optional)\n  — extensions for this utility to change how tokens are turned into a tree\n\n### `Token`\n\nToken from micromark (TypeScript type).\n\n###### Type\n\n```ts\ntype Token = { /* … */ }\n```\n\n### `Transform`\n\nExtra transform, to change the AST afterwards (TypeScript type).\n\n###### Parameters\n\n* `tree` ([`Root`][github-mdast-root])\n  — tree to transform\n\n###### Returns\n\nNew tree ([`Root`][github-mdast-root]) or nothing\n(in which case the current tree is used).\n\n### `Value`\n\nContents of the file (TypeScript type).\n\nSee [`micromark`][github-micromark-api] for more info.\n\n###### Type\n\n```ts\ntype Value = Uint8Array | string\n```\n\n## List of extensions\n\n* [`syntax-tree/mdast-util-directive`][github-mdast-util-directive]\n  — directives\n* [`syntax-tree/mdast-util-frontmatter`][github-mdast-util-frontmatter]\n  — frontmatter (YAML, TOML, more)\n* [`syntax-tree/mdast-util-gfm`][github-mdast-util-gfm]\n  — GFM\n* [`syntax-tree/mdast-util-gfm-autolink-literal`](https://github.com/syntax-tree/mdast-util-gfm-autolink-literal)\n  — GFM autolink literals\n* [`syntax-tree/mdast-util-gfm-footnote`](https://github.com/syntax-tree/mdast-util-gfm-footnote)\n  — GFM footnotes\n* [`syntax-tree/mdast-util-gfm-strikethrough`](https://github.com/syntax-tree/mdast-util-gfm-strikethrough)\n  — GFM strikethrough\n* [`syntax-tree/mdast-util-gfm-table`](https://github.com/syntax-tree/mdast-util-gfm-table)\n  — GFM tables\n* [`syntax-tree/mdast-util-gfm-task-list-item`](https://github.com/syntax-tree/mdast-util-gfm-task-list-item)\n  — GFM task list items\n* [`syntax-tree/mdast-util-math`][github-mdast-util-math]\n  — math\n* [`syntax-tree/mdast-util-mdx`][github-mdast-util-mdx]\n  — MDX\n* [`syntax-tree/mdast-util-mdx-expression`](https://github.com/syntax-tree/mdast-util-mdx-expression)\n  — MDX expressions\n* [`syntax-tree/mdast-util-mdx-jsx`](https://github.com/syntax-tree/mdast-util-mdx-jsx)\n  — MDX JSX\n* [`syntax-tree/mdast-util-mdxjs-esm`](https://github.com/syntax-tree/mdast-util-mdxjs-esm)\n  — MDX ESM\n\n## Syntax\n\nMarkdown is parsed according to CommonMark.\nExtensions can add support for other syntax.\nIf you’re interested in extending markdown,\n[more information is available in micromark’s\nreadme][github-micromark-extension].\n\n## Syntax tree\n\nThe syntax tree is [mdast][github-mdast].\n\n## Types\n\nThis package is fully typed with [TypeScript][].\nIt exports the additional types\n[`CompileContext`][api-compile-context],\n[`CompileData`][api-compile-data],\n[`Encoding`][api-encoding],\n[`Extension`][api-extension],\n[`Handle`][api-handle],\n[`OnEnterError`][api-on-enter-error],\n[`OnExitError`][api-on-exit-error],\n[`Options`][api-options],\n[`Token`][api-token],\n[`Transform`][api-transform], and\n[`Value`][api-value].\n\n## Compatibility\n\nProjects maintained by the unified collective are compatible with maintained\nversions of Node.js.\n\nWhen we cut a new major release, we drop support for unmaintained versions of\nNode.\nThis means we try to keep the current release line,\n`mdast-util-from-markdown@^2`, compatible with Node.js 16.\n\n## Security\n\nAs markdown is sometimes used for HTML, and improper use of HTML can open you up\nto a [cross-site scripting (XSS)][wikipedia-xss] attack, use of `mdast-util-from-markdown`\ncan also be unsafe.\nWhen going to HTML, use this utility in combination with\n[`hast-util-sanitize`][github-hast-util-sanitize] to make the tree safe.\n\n## Related\n\n* [`syntax-tree/mdast-util-to-markdown`](https://github.com/syntax-tree/mdast-util-to-markdown)\n  — serialize mdast as markdown\n* [`micromark/micromark`][github-micromark]\n  — parse markdown\n* [`remarkjs/remark`][github-remark]\n  — process markdown\n\n## Contribute\n\nSee [`contributing.md`][health-contributing]\nin\n[`syntax-tree/.github`][health]\nfor ways to get started.\nSee [`support.md`][health-support] for ways to get help.\n\nThis project has a [code of conduct][health-coc].\nBy interacting with this repository, organization, or community you agree to\nabide by its terms.\n\n## License\n\n[MIT][file-license] © [Titus Wormer][wooorm]\n\n\u003c!-- Definitions --\u003e\n\n[api-compile-context]: #compilecontext\n\n[api-compile-data]: #compiledata\n\n[api-encoding]: #encoding\n\n[api-extension]: #extension\n\n[api-from-markdown]: #frommarkdownvalue-encoding-options\n\n[api-handle]: #handle\n\n[api-on-enter-error]: #onentererror\n\n[api-on-exit-error]: #onexiterror\n\n[api-options]: #options\n\n[api-token]: #token\n\n[api-transform]: #transform\n\n[api-value]: #value\n\n[badge-build-image]: https://github.com/syntax-tree/mdast-util-from-markdown/workflows/main/badge.svg\n\n[badge-build-url]: https://github.com/syntax-tree/mdast-util-from-markdown/actions\n\n[badge-coverage-image]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-from-markdown.svg\n\n[badge-coverage-url]: https://codecov.io/github/syntax-tree/mdast-util-from-markdown\n\n[badge-downloads-image]: https://img.shields.io/npm/dm/mdast-util-from-markdown.svg\n\n[badge-downloads-url]: https://www.npmjs.com/package/mdast-util-from-markdown\n\n[badge-size-image]: https://img.shields.io/bundlejs/size/mdast-util-from-markdown\n\n[badge-size-url]: https://bundlejs.com/?q=mdast-util-from-markdown\n\n[esmsh]: https://esm.sh\n\n[file-license]: license\n\n[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c\n\n[github-hast-util-sanitize]: https://github.com/syntax-tree/hast-util-sanitize\n\n[github-mdast]: https://github.com/syntax-tree/mdast\n\n[github-mdast-nodes]: https://github.com/syntax-tree/mdast#nodes\n\n[github-mdast-root]: https://github.com/syntax-tree/mdast#root\n\n[github-mdast-util-directive]: https://github.com/syntax-tree/mdast-util-directive\n\n[github-mdast-util-frontmatter]: https://github.com/syntax-tree/mdast-util-frontmatter\n\n[github-mdast-util-gfm]: https://github.com/syntax-tree/mdast-util-gfm\n\n[github-mdast-util-math]: https://github.com/syntax-tree/mdast-util-math\n\n[github-mdast-util-mdx]: https://github.com/syntax-tree/mdast-util-mdx\n\n[github-micromark]: https://github.com/micromark/micromark\n\n[github-micromark-api]: https://github.com/micromark/micromark/tree/main/packages/micromark#micromarkvalue-encoding-options\n\n[github-micromark-extension]: https://github.com/micromark/micromark#extensions\n\n[github-remark]: https://github.com/remarkjs/remark\n\n[github-remark-parse]: https://github.com/remarkjs/remark/tree/main/packages/remark-parse\n\n[health]: https://github.com/syntax-tree/.github\n\n[health-coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md\n\n[health-contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md\n\n[health-support]: https://github.com/syntax-tree/.github/blob/main/support.md\n\n[mozilla-uint8-array]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array\n\n[node-packages-conditions]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions\n\n[node-util-encoding]: https://nodejs.org/api/util.html#whatwg-supported-encodings\n\n[npmjs-install]: https://docs.npmjs.com/cli/install\n\n[typescript]: https://www.typescriptlang.org\n\n[wikipedia-xss]: https://en.wikipedia.org/wiki/Cross-site_scripting\n\n[wooorm]: https://wooorm.com\n","funding_links":["https://github.com/sponsors/unifiedjs","https://opencollective.com/unified","https://thanks.dev/u/gh/syntax-tree"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyntax-tree%2Fmdast-util-from-markdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsyntax-tree%2Fmdast-util-from-markdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyntax-tree%2Fmdast-util-from-markdown/lists"}