{"id":13482762,"url":"https://github.com/syntax-tree/mdast-util-math","last_synced_at":"2025-08-12T18:20:51.891Z","repository":{"id":57293492,"uuid":"301964663","full_name":"syntax-tree/mdast-util-math","owner":"syntax-tree","description":"mdast extension to parse and serialize math","archived":false,"fork":false,"pushed_at":"2023-07-16T11:25:45.000Z","size":125,"stargazers_count":16,"open_issues_count":0,"forks_count":4,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-11-14T22:05:05.993Z","etag":null,"topics":["latex","math","mdast","mdast-util","tex","unist"],"latest_commit_sha":null,"homepage":"https://unifiedjs.com","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},"funding":{"github":"unifiedjs","open_collective":"unified"}},"created_at":"2020-10-07T07:54:17.000Z","updated_at":"2024-09-10T05:03:43.000Z","dependencies_parsed_at":"2024-01-21T09:48:09.632Z","dependency_job_id":"b90c4901-0342-455c-b321-e78bb01fd3bc","html_url":"https://github.com/syntax-tree/mdast-util-math","commit_stats":{"total_commits":50,"total_committers":1,"mean_commits":50.0,"dds":0.0,"last_synced_commit":"17b41eb86e87f1ae00c3e71081a6f3a47fad3aa4"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syntax-tree%2Fmdast-util-math","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syntax-tree%2Fmdast-util-math/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syntax-tree%2Fmdast-util-math/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syntax-tree%2Fmdast-util-math/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/syntax-tree","download_url":"https://codeload.github.com/syntax-tree/mdast-util-math/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245854643,"owners_count":20683393,"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":["latex","math","mdast","mdast-util","tex","unist"],"created_at":"2024-07-31T17:01:05.283Z","updated_at":"2025-03-27T13:32:37.243Z","avatar_url":"https://github.com/syntax-tree.png","language":"JavaScript","readme":"# mdast-util-math\n\n[![Build][build-badge]][build]\n[![Coverage][coverage-badge]][coverage]\n[![Downloads][downloads-badge]][downloads]\n[![Size][size-badge]][size]\n[![Sponsors][sponsors-badge]][collective]\n[![Backers][backers-badge]][collective]\n[![Chat][chat-badge]][chat]\n\n[mdast][] extensions to parse and serialize math (`$C_L$`).\n\n## Contents\n\n*   [What is this?](#what-is-this)\n*   [When to use this](#when-to-use-this)\n*   [Install](#install)\n*   [Use](#use)\n*   [API](#api)\n    *   [`mathFromMarkdown()`](#mathfrommarkdown)\n    *   [`mathToMarkdown(options?)`](#mathtomarkdownoptions)\n    *   [`InlineMath`](#inlinemath)\n    *   [`Math`](#math)\n    *   [`ToOptions`](#tooptions)\n*   [HTML](#html)\n*   [Syntax](#syntax)\n*   [Syntax tree](#syntax-tree)\n    *   [Nodes](#nodes)\n    *   [Content model](#content-model)\n*   [Types](#types)\n*   [Compatibility](#compatibility)\n*   [Related](#related)\n*   [Contribute](#contribute)\n*   [License](#license)\n\n## What is this?\n\nThis package contains two extensions that add support for math syntax in\nmarkdown to [mdast][].\nThese extensions plug into\n[`mdast-util-from-markdown`][mdast-util-from-markdown] (to support parsing\nmath in markdown into a syntax tree) and\n[`mdast-util-to-markdown`][mdast-util-to-markdown] (to support serializing\nmath in syntax trees to markdown).\n\n## When to use this\n\nThis project is useful when you want to support math in markdown.\nExtending markdown with a syntax extension makes the markdown less portable.\nLaTeX equations are also quite hard.\nBut this mechanism works well when you want authors, that have some LaTeX\nexperience, to be able to embed rich diagrams of math in scientific text.\n\nYou can use these extensions when you are working with\n`mdast-util-from-markdown` and `mdast-util-to-markdown` already.\n\nWhen working with `mdast-util-from-markdown`, you must combine this package\nwith [`micromark-extension-math`][micromark-extension-math].\n\nWhen you don’t need a syntax tree, you can use [`micromark`][micromark]\ndirectly with\n[`micromark-extension-math`][micromark-extension-math].\n\nAll these packages are used [`remark-math`][remark-math], which\nfocusses on making it easier to transform content by abstracting these\ninternals away.\n\nThis utility adds [fields on nodes][fields] so that the utility responsible for\nturning mdast (markdown) nodes into hast (HTML) nodes,\n[`mdast-util-to-hast`][mdast-util-to-hast], turns text (inline) math nodes into\n`\u003ccode class=\"language-math math-inline\"\u003e…\u003c/code\u003e` and flow (block) math nodes\ninto `\u003cpre\u003e\u003ccode class=\"language-math math-display\"\u003e…\u003c/code\u003e\u003c/pre\u003e`.\n\n## Install\n\nThis package is [ESM only][esm].\nIn Node.js (version 16+), install with [npm][]:\n\n```sh\nnpm install mdast-util-math\n```\n\nIn Deno with [`esm.sh`][esmsh]:\n\n```js\nimport {mathFromMarkdown, mathToMarkdown} from 'https://esm.sh/mdast-util-math@3'\n```\n\nIn browsers with [`esm.sh`][esmsh]:\n\n```html\n\u003cscript type=\"module\"\u003e\n  import {mathFromMarkdown, mathToMarkdown} from 'https://esm.sh/mdast-util-math@3?bundle'\n\u003c/script\u003e\n```\n\n## Use\n\nSay our document `example.md` contains:\n\n```markdown\nLift($L$) can be determined by Lift Coefficient ($C_L$) like the following\nequation.\n\n$$\nL = \\frac{1}{2} \\rho v^2 S C_L\n$$\n```\n\n…and our module `example.js` looks as follows:\n\n```js\nimport fs from 'node:fs/promises'\nimport {math} from 'micromark-extension-math'\nimport {fromMarkdown} from 'mdast-util-from-markdown'\nimport {mathFromMarkdown, mathToMarkdown} from 'mdast-util-math'\nimport {toMarkdown} from 'mdast-util-to-markdown'\n\nconst doc = await fs.readFile('example.md')\n\nconst tree = fromMarkdown(doc, {\n  extensions: [math()],\n  mdastExtensions: [mathFromMarkdown()]\n})\n\nconsole.log(tree)\n\nconst out = toMarkdown(tree, {extensions: [mathToMarkdown()]})\n\nconsole.log(out)\n```\n\n…now running `node example.js` yields (positional info and data removed for\nbrevity):\n\n```js\n{\n  type: 'root',\n  children: [\n    {\n      type: 'paragraph',\n      children: [\n        {type: 'text', value: 'Lift('},\n        {type: 'inlineMath', value: 'L', data: {/* … */}},\n        {type: 'text', value: ') can be determined by Lift Coefficient ('},\n        {type: 'inlineMath', value: 'C_L', data: {/* … */}},\n        {type: 'text', value: ') like the following\\nequation.'}\n      ]\n    },\n    {type: 'math', meta: null, value: 'L = \\\\frac{1}{2} \\\\rho v^2 S C_L', data: {/* … */}}\n  ]\n}\n```\n\n```markdown\nLift($L$) can be determined by Lift Coefficient ($C_L$) like the following\nequation.\n\n$$\nL = \\frac{1}{2} \\rho v^2 S C_L\n$$\n```\n\n## API\n\nThis package exports the identifiers\n[`mathFromMarkdown`][api-math-from-markdown]\nand [`mathToMarkdown`][api-math-to-markdown].\nThere is no default export.\n\n### `mathFromMarkdown()`\n\nCreate an extension for [`mdast-util-from-markdown`][mdast-util-from-markdown].\n\n###### Returns\n\nExtension for `mdast-util-from-markdown`\n([`FromMarkdownExtension`][from-markdown-extension]).\n\n### `mathToMarkdown(options?)`\n\nCreate an extension for [`mdast-util-to-markdown`][mdast-util-to-markdown].\n\n###### Parameters\n\n*   `options` ([`ToOptions`][api-to-options], optional)\n    — configuration\n\n###### Returns\n\nExtension for `mdast-util-to-markdown`\n([`ToMarkdownExtension`][to-markdown-extension]).\n\n### `InlineMath`\n\nMath (text) (TypeScript type).\n\n###### Type\n\n```ts\nimport type {Data, Literal} from 'mdast'\n\ninterface InlineMath extends Literal {\n  type: 'inlineMath'\n  data?: InlineMathData | undefined\n}\n\nexport interface InlineMathData extends Data {}\n```\n\n### `Math`\n\nMath (flow) (TypeScript type).\n\n###### Type\n\n```ts\nimport type {Data, Literal} from 'mdast'\n\ninterface Math extends Literal {\n  type: 'math'\n  meta?: string | null | undefined\n  data?: MathData | undefined\n}\n\nexport interface MathData extends Data {}\n```\n\n### `ToOptions`\n\nConfiguration (TypeScript type).\n\n###### Fields\n\n*   `singleDollarTextMath` (`boolean`, default: `true`)\n    — whether to support math (text) with a single dollar.\n    Single dollars work in Pandoc and many other places, but often interfere\n    with “normal” dollars in text.\n    If you turn this off, you can still use two or more dollars for text math\n\n## HTML\n\nThis plugin integrates with [`mdast-util-to-hast`][mdast-util-to-hast].\nWhen mdast is turned into hast the math nodes are turned into\n`\u003ccode class=\"language-math math-inline\"\u003e…\u003c/code\u003e` and\n`\u003cpre\u003e\u003ccode class=\"language-math math-display\"\u003e…\u003c/code\u003e\u003c/pre\u003e` elements.\n\n## Syntax\n\nSee [Syntax in `micromark-extension-frontmatter`][syntax].\n\n## Syntax tree\n\nThe following interfaces are added to **[mdast][]** by this utility.\n\n### Nodes\n\n#### `Math`\n\n```idl\ninterface Math \u003c: Literal {\n  type: 'code'\n  meta: string?\n}\n```\n\n**Math** (**[Literal][dfn-literal]**) represents a block of math,\nsuch as LaTeX mathematical expressions.\n\n**Math** can be used where **[flow][dfn-flow-content]** content is expected.\nIts content is represented by its `value` field.\n\nThis node relates to the **[phrasing][dfn-phrasing-content]** content concept\n**[InlineMath][dfn-inline-math]**.\n\nA `meta` field can be present.\nIt represents custom information relating to the node.\n\nFor example, the following markdown:\n\n```markdown\n$$\nL = \\frac{1}{2} \\rho v^2 S C_L\n$$\n```\n\nYields:\n\n```js\n{\n  type: 'math',\n  meta: null,\n  value: 'L = \\\\frac{1}{2} \\\\rho v^2 S C_L',\n  data: {/* … */}\n}\n```\n\n#### `InlineMath`\n\n```idl\ninterface InlineMath \u003c: Literal {\n  type: 'inlineMath'\n}\n```\n\n**InlineMath** (**[Literal][dfn-literal]**) represents a fragment of computer\ncode, such as a file name, computer program, or anything a computer could parse.\n\n**InlineMath** can be used where **[phrasing][dfn-phrasing-content]** content\nis expected.\nIts content is represented by its `value` field.\n\nThis node relates to the **[flow][dfn-flow-content]** content concept\n**[Math][dfn-math]**.\n\nFor example, the following markdown:\n\n```markdown\n$L$\n```\n\nYields:\n\n```js\n{type: 'inlineMath', value: 'L', data: {/* … */}}\n```\n\n### Content model\n\n#### `FlowContent` (math)\n\n```idl\ntype FlowContentMath = Math | FlowContent\n```\n\n#### `PhrasingContent` (math)\n\n```idl\ntype PhrasingContentMath = InlineMath | PhrasingContent\n```\n\n## Types\n\nThis package is fully typed with [TypeScript][].\nIt exports the additional types [`InlineMath`][api-inline-math],\n[`Math`][api-math], and [`ToOptions`][api-to-options].\n\nIt also registers the node types with `@types/mdast`.\nIf you’re working with the syntax tree, make sure to import this utility\nsomewhere in your types, as that registers the new node types in the tree.\n\n```js\n/**\n * @typedef {import('mdast-util-math')}\n */\n\nimport {visit} from 'unist-util-visit'\n\n/** @type {import('mdast').Root} */\nconst tree = getMdastNodeSomeHow()\n\nvisit(tree, function (node) {\n  // `node` can now be one of the nodes for math.\n})\n```\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, `mdast-util-math@^3`,\ncompatible with Node.js 16.\n\nThis plugin works with `mdast-util-from-markdown` version 2+ and\n`mdast-util-to-markdown` version 2+.\n\n## Related\n\n*   [`remark-math`][remark-math]\n    — remark plugin to support math\n*   [`micromark-extension-math`][micromark-extension-math]\n    — micromark extension to parse math\n\n## Contribute\n\nSee [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for\nways to get started.\nSee [`support.md`][support] for ways to get help.\n\nThis project has a [code of conduct][coc].\nBy interacting with this repository, organization, or community you agree to\nabide by its terms.\n\n## License\n\n[MIT][license] © [Titus Wormer][author]\n\n\u003c!-- Definitions --\u003e\n\n[build-badge]: https://github.com/syntax-tree/mdast-util-math/workflows/main/badge.svg\n\n[build]: https://github.com/syntax-tree/mdast-util-math/actions\n\n[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-math.svg\n\n[coverage]: https://codecov.io/github/syntax-tree/mdast-util-math\n\n[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-math.svg\n\n[downloads]: https://www.npmjs.com/package/mdast-util-math\n\n[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size\u0026query=$.size.compressedSize\u0026url=https://deno.bundlejs.com/?q=mdast-util-math\n\n[size]: https://bundlejs.com/?q=mdast-util-math\n\n[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg\n\n[backers-badge]: https://opencollective.com/unified/backers/badge.svg\n\n[collective]: https://opencollective.com/unified\n\n[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg\n\n[chat]: https://github.com/syntax-tree/unist/discussions\n\n[npm]: https://docs.npmjs.com/cli/install\n\n[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c\n\n[esmsh]: https://esm.sh\n\n[typescript]: https://www.typescriptlang.org\n\n[license]: license\n\n[author]: https://wooorm.com\n\n[health]: https://github.com/syntax-tree/.github\n\n[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md\n\n[support]: https://github.com/syntax-tree/.github/blob/main/support.md\n\n[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md\n\n[remark-math]: https://github.com/remarkjs/remark-math\n\n[mdast]: https://github.com/syntax-tree/mdast\n\n[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown\n\n[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown\n\n[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast\n\n[micromark]: https://github.com/micromark/micromark\n\n[micromark-extension-math]: https://github.com/micromark/micromark-extension-math\n\n[syntax]: https://github.com/micromark/micromark-extension-math#syntax\n\n[fields]: https://github.com/syntax-tree/mdast-util-to-hast#fields-on-nodes\n\n[dfn-literal]: https://github.com/syntax-tree/mdast#literal\n\n[from-markdown-extension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension\n\n[to-markdown-extension]: https://github.com/syntax-tree/mdast-util-to-markdown#options\n\n[api-math-from-markdown]: #mathfrommarkdown\n\n[api-math-to-markdown]: #mathtomarkdownoptions\n\n[api-math]: #math\n\n[api-inline-math]: #inlinemath\n\n[api-to-options]: #tooptions\n\n[dfn-flow-content]: #flowcontent-math\n\n[dfn-phrasing-content]: #phrasingcontent-math\n\n[dfn-inline-math]: #inlinemath-1\n\n[dfn-math]: #math-1\n","funding_links":["https://github.com/sponsors/unifiedjs","https://opencollective.com/unified"],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyntax-tree%2Fmdast-util-math","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsyntax-tree%2Fmdast-util-math","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyntax-tree%2Fmdast-util-math/lists"}