{"id":29125778,"url":"https://github.com/syntax-tree/mdast-util-frontmatter","last_synced_at":"2025-06-29T22:03:41.625Z","repository":{"id":57293477,"uuid":"294485093","full_name":"syntax-tree/mdast-util-frontmatter","owner":"syntax-tree","description":"mdast extensions to parse and serialize frontmatter (YAML, TOML, etc)","archived":false,"fork":false,"pushed_at":"2023-09-14T12:24:04.000Z","size":98,"stargazers_count":18,"open_issues_count":0,"forks_count":0,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-06-14T18:09:10.227Z","etag":null,"topics":["frontmatter","gfm","mdast","mdast-util","toml","util","yaml"],"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,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"unifiedjs","open_collective":"unified"}},"created_at":"2020-09-10T18:03:08.000Z","updated_at":"2025-05-06T07:06:57.000Z","dependencies_parsed_at":"2024-06-18T18:20:11.955Z","dependency_job_id":"30d4046c-94c0-4bc1-8a6b-fca6bbe9f8cc","html_url":"https://github.com/syntax-tree/mdast-util-frontmatter","commit_stats":{"total_commits":54,"total_committers":1,"mean_commits":54.0,"dds":0.0,"last_synced_commit":"d76616b88bdafdbbcd97247c4d3a8a41cc71ae48"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/syntax-tree/mdast-util-frontmatter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syntax-tree%2Fmdast-util-frontmatter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syntax-tree%2Fmdast-util-frontmatter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syntax-tree%2Fmdast-util-frontmatter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syntax-tree%2Fmdast-util-frontmatter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/syntax-tree","download_url":"https://codeload.github.com/syntax-tree/mdast-util-frontmatter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syntax-tree%2Fmdast-util-frontmatter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261937022,"owners_count":23232843,"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":["frontmatter","gfm","mdast","mdast-util","toml","util","yaml"],"created_at":"2025-06-29T22:03:40.856Z","updated_at":"2025-06-29T22:03:41.608Z","avatar_url":"https://github.com/syntax-tree.png","language":"JavaScript","readme":"# mdast-util-frontmatter\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 frontmatter (YAML, TOML, and more).\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    *   [`frontmatterFromMarkdown(options?)`](#frontmatterfrommarkdownoptions)\n    *   [`frontmatterToMarkdown(options?)`](#frontmattertomarkdownoptions)\n    *   [`Info`](#info)\n    *   [`Matter`](#matter)\n    *   [`Options`](#options)\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 frontmatter syntax\nas often used in markdown to [mdast][].\nThese extensions plug into\n[`mdast-util-from-markdown`][mdast-util-from-markdown] (to support parsing\nfrontmatter in markdown into a syntax tree) and\n[`mdast-util-to-markdown`][mdast-util-to-markdown] (to support serializing\nfrontmatter in syntax trees to markdown).\n\nFrontmatter is a metadata format in front of the content.\nIt’s typically written in YAML and is often used with markdown.\nFrontmatter does not work everywhere so it makes markdown less portable.\n\nThese extensions follow how GitHub handles frontmatter.\nGitHub only supports YAML frontmatter, but these extensions also support\ndifferent flavors (such as TOML).\n\n## When to use this\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-frontmatter`][micromark-extension-frontmatter].\n\nWhen you don’t need a syntax tree, you can use [`micromark`][micromark]\ndirectly with\n[`micromark-extension-frontmatter`][micromark-extension-frontmatter].\n\nAll these packages are used [`remark-frontmatter`][remark-frontmatter], which\nfocusses on making it easier to transform content by abstracting these\ninternals away.\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-frontmatter\n```\n\nIn Deno with [`esm.sh`][esmsh]:\n\n```js\nimport {frontmatterFromMarkdown, frontmatterToMarkdown} from 'https://esm.sh/mdast-util-frontmatter@2'\n```\n\nIn browsers with [`esm.sh`][esmsh]:\n\n```html\n\u003cscript type=\"module\"\u003e\n  import {frontmatterFromMarkdown, frontmatterToMarkdown} from 'https://esm.sh/mdast-util-frontmatter@2?bundle'\n\u003c/script\u003e\n```\n\n## Use\n\nSay our document `example.md` contains:\n\n```markdown\n+++\ntitle = \"New Website\"\n+++\n\n# Other markdown\n```\n\n…and our module `example.js` looks as follows:\n\n```js\nimport fs from 'node:fs/promises'\nimport {frontmatter} from 'micromark-extension-frontmatter'\nimport {fromMarkdown} from 'mdast-util-from-markdown'\nimport {frontmatterFromMarkdown, frontmatterToMarkdown} from 'mdast-util-frontmatter'\nimport {toMarkdown} from 'mdast-util-to-markdown'\n\nconst doc = await fs.readFile('example.md')\n\nconst tree = fromMarkdown(doc, {\n  extensions: [frontmatter(['yaml', 'toml'])],\n  mdastExtensions: [frontmatterFromMarkdown(['yaml', 'toml'])]\n})\n\nconsole.log(tree)\n\nconst out = toMarkdown(tree, {extensions: [frontmatterToMarkdown(['yaml', 'toml'])]})\n\nconsole.log(out)\n```\n\n…now running `node example.js` yields (positional info removed for brevity):\n\n```js\n{\n  type: 'root',\n  children: [\n    {type: 'toml', value: 'title = \"New Website\"'},\n    {\n      type: 'heading',\n      depth: 1,\n      children: [{type: 'text', value: 'Other markdown'}]\n    }\n  ]\n}\n```\n\n```markdown\n+++\ntitle = \"New Website\"\n+++\n\n# Other markdown\n```\n\n## API\n\nThis package exports the identifiers\n[`frontmatterFromMarkdown`][api-frontmatter-from-markdown] and\n[`frontmatterToMarkdown`][api-frontmatter-to-markdown].\nThere is no default export.\n\n### `frontmatterFromMarkdown(options?)`\n\nCreate an extension for\n[`mdast-util-from-markdown`][mdast-util-from-markdown].\n\n###### Parameters\n\n*   `options` ([`Options`][api-options], optional)\n    — configuration\n\n###### Returns\n\nExtension for `mdast-util-from-markdown`\n([`FromMarkdownExtension`][from-markdown-extension]).\n\n### `frontmatterToMarkdown(options?)`\n\nCreate an extension for\n[`mdast-util-to-markdown`][mdast-util-to-markdown].\n\n###### Parameters\n\n*   `options` ([`Options`][api-options], optional)\n    — configuration\n\n###### Returns\n\nExtension for `mdast-util-to-markdown`\n([`ToMarkdownExtension`][to-markdown-extension]).\n\n### `Info`\n\nStructure of marker or fence (TypeScript type).\n\nSame as [`Info` from `micromark-extension-frontmatter`][micromark-info].\n\n### `Matter`\n\nStructure of matter (TypeScript type).\n\nSame as [`Matter` from `micromark-extension-frontmatter`][micromark-matter].\n\n### `Options`\n\nConfiguration (TypeScript type).\n\nSame as [`Options` from `micromark-extension-frontmatter`][micromark-options].\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\u003e 👉 **Note**: other nodes are not enabled by default, but when passing options\n\u003e to enable them, they work the same as YAML.\n\n#### `YAML`\n\n```idl\ninterface YAML \u003c: Literal {\n  type: \"yaml\"\n}\n```\n\n**YAML** (**[Literal][dfn-literal]**) represents a collection of metadata for\nthe document in the YAML data serialization language.\n\n**YAML** can be used where **[frontmatter][dfn-frontmatter-content]** content\nis expected.\nIts content is represented by its `value` field.\n\nFor example, the following markdown:\n\n```markdown\n---\nfoo: bar\n---\n```\n\nYields:\n\n```js\n{type: 'yaml', value: 'foo: bar'}\n```\n\n### Content model\n\n#### `FrontmatterContent`\n\n```idl\ntype FrontmatterContent = YAML\n```\n\n**Frontmatter** content represent out-of-band information about the document.\n\nIf frontmatter is present, it must be limited to one node in the\n*[tree][term-tree]*, and can only exist as a *[head][term-head]*.\n\n#### `FlowContent` (frontmatter)\n\n```idl\ntype FlowContentFrontmatter = FrontmatterContent | FlowContent\n```\n\n## Types\n\nThis package is fully typed with [TypeScript][].\nIt exports the additional types [`Info`][api-info], [`Matter`][api-matter],\nand [`Options`][api-options].\n\nThe YAML node type is supported in `@types/mdast` by default.\nTo add other node types, register them by adding them to\n`FrontmatterContentMap`:\n\n```ts\nimport type {Literal} from 'mdast'\n\ninterface Toml extends Literal {\n  type: 'toml'\n}\n\ndeclare module 'mdast' {\n  interface FrontmatterContentMap {\n    // Allow using TOML nodes defined by `mdast-util-frontmatter`.\n    toml: Toml\n  }\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,\n`mdast-util-frontmatter@^2`, compatible with Node.js 16.\n\nThis utility works with `mdast-util-from-markdown` version 2+ and\n`mdast-util-to-markdown` version 2+.\n\n## Related\n\n*   [`remark-frontmatter`][remark-frontmatter]\n    — remark plugin to support frontmatter\n*   [`micromark-extension-frontmatter`][micromark-extension-frontmatter]\n    — micromark extension to parse frontmatter\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-frontmatter/workflows/main/badge.svg\n\n[build]: https://github.com/syntax-tree/mdast-util-frontmatter/actions\n\n[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-frontmatter.svg\n\n[coverage]: https://codecov.io/github/syntax-tree/mdast-util-frontmatter\n\n[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-frontmatter.svg\n\n[downloads]: https://www.npmjs.com/package/mdast-util-frontmatter\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-frontmatter\n\n[size]: https://bundlejs.com/?q=mdast-util-frontmatter\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[mdast]: https://github.com/syntax-tree/mdast\n\n[remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter\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[micromark]: https://github.com/micromark/micromark\n\n[micromark-extension-frontmatter]: https://github.com/micromark/micromark-extension-frontmatter\n\n[micromark-info]: https://github.com/micromark/micromark-extension-frontmatter#info\n\n[micromark-matter]: https://github.com/micromark/micromark-extension-frontmatter#matter\n\n[micromark-options]: https://github.com/micromark/micromark-extension-frontmatter#options\n\n[syntax]: https://github.com/micromark/micromark-extension-frontmatter#syntax\n\n[dfn-literal]: https://github.com/syntax-tree/mdast#literal\n\n[term-tree]: https://github.com/syntax-tree/unist#tree\n\n[term-head]: https://github.com/syntax-tree/unist#head\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[dfn-frontmatter-content]: #frontmattercontent\n\n[api-frontmatter-from-markdown]: #frontmatterfrommarkdownoptions\n\n[api-frontmatter-to-markdown]: #frontmattertomarkdownoptions\n\n[api-info]: #info\n\n[api-matter]: #matter\n\n[api-options]: #options\n","funding_links":["https://github.com/sponsors/unifiedjs","https://opencollective.com/unified"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyntax-tree%2Fmdast-util-frontmatter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsyntax-tree%2Fmdast-util-frontmatter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyntax-tree%2Fmdast-util-frontmatter/lists"}