{"id":13538154,"url":"https://github.com/micromark/micromark-extension-frontmatter","last_synced_at":"2025-04-05T06:02:17.491Z","repository":{"id":41529596,"uuid":"294464999","full_name":"micromark/micromark-extension-frontmatter","owner":"micromark","description":"micromark extension to support frontmatter (YAML, TOML, etc)","archived":false,"fork":false,"pushed_at":"2025-02-25T13:18:28.000Z","size":112,"stargazers_count":21,"open_issues_count":1,"forks_count":2,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-29T05:01:43.456Z","etag":null,"topics":["frontmatter","gfm","markdown","micromark","micromark-extension","toml","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/micromark.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-10T16:34:26.000Z","updated_at":"2025-03-07T17:21:25.000Z","dependencies_parsed_at":"2024-01-16T15:40:29.215Z","dependency_job_id":"079c81e9-7f28-4708-aa7c-b895cfed7f64","html_url":"https://github.com/micromark/micromark-extension-frontmatter","commit_stats":{"total_commits":47,"total_committers":2,"mean_commits":23.5,"dds":"0.021276595744680882","last_synced_commit":"1ee3890aef25d6a4ff5ceffc53d00c04cf2438dc"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micromark%2Fmicromark-extension-frontmatter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micromark%2Fmicromark-extension-frontmatter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micromark%2Fmicromark-extension-frontmatter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micromark%2Fmicromark-extension-frontmatter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/micromark","download_url":"https://codeload.github.com/micromark/micromark-extension-frontmatter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247294514,"owners_count":20915340,"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","markdown","micromark","micromark-extension","toml","yaml"],"created_at":"2024-08-01T09:01:07.197Z","updated_at":"2025-04-05T06:02:17.471Z","avatar_url":"https://github.com/micromark.png","language":"JavaScript","funding_links":["https://github.com/sponsors/unifiedjs","https://opencollective.com/unified"],"categories":["JavaScript"],"sub_categories":[],"readme":"# micromark-extension-frontmatter\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[micromark][github-micromark] extensions to support frontmatter\n(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  * [`frontmatter(options?)`](#frontmatteroptions)\n  * [`frontmatterHtml(options?)`](#frontmatterhtmloptions)\n  * [`toMatters(options?)`](#tomattersoptions)\n  * [`Info`](#info)\n  * [`Matter`](#matter)\n  * [`Options`](#options)\n  * [`Preset`](#preset)\n* [Examples](#examples)\n* [Authoring](#authoring)\n* [HTML](#html)\n* [CSS](#css)\n* [Syntax](#syntax)\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 contains two extensions that add support for frontmatter syntax\nas often used in markdown to [`micromark`][github-micromark].\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\nAs there is no spec for frontmatter in markdown, these extensions follow how\nYAML frontmatter works on `github.com`.\nIt can also parse TOML frontmatter, just like YAML except that it uses a `+`.\n\n## When to use this\n\nYou can use these extensions when you are working with\n[`micromark`][github-micromark] already.\n\nWhen you need a syntax tree, you can combine this package with\n[`mdast-util-frontmatter`][github-mdast-util-frontmatter].\n\nAll these packages are used [`remark-frontmatter`][github-remark-frontmatter],\nwhich focusses on making it easier to transform content by abstracting these\ninternals away.\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 micromark-extension-frontmatter\n```\n\nIn Deno with [`esm.sh`][esmsh]:\n\n```js\nimport {frontmatter, frontmatterHtml} from 'https://esm.sh/micromark-extension-frontmatter@2'\n```\n\nIn browsers with [`esm.sh`][esmsh]:\n\n```html\n\u003cscript type=\"module\"\u003e\n  import {frontmatter, frontmatterHtml} from 'https://esm.sh/micromark-extension-frontmatter@2?bundle'\n\u003c/script\u003e\n```\n\n## Use\n\nSay our module `example.js` looks as follows:\n\n```js\nimport {micromark} from 'micromark'\nimport {frontmatter, frontmatterHtml} from 'micromark-extension-frontmatter'\n\nconst output = micromark('---\\na: b\\n---\\n# c', {\n  extensions: [frontmatter()],\n  htmlExtensions: [frontmatterHtml()]\n})\n\nconsole.log(output)\n```\n\n…now running `node example.js` yields:\n\n```html\n\u003ch1\u003ec\u003c/h1\u003e\n```\n\n## API\n\nThis package exports the identifiers [`frontmatter`][api-frontmatter],\n[`frontmatterHtml`][api-frontmatter-html], and [`toMatters`][api-to-matters].\nThere is no default export.\n\nThe export map supports the\n[`development` condition][nodejs-condition-development].\nRun `node --conditions development module.js` to get instrumented dev code.\nWithout this condition, production code is loaded.\n\n### `frontmatter(options?)`\n\nCreate an extension for [`micromark`][github-micromark]\nto enable frontmatter syntax.\n\n###### Parameters\n\n* `options` ([`Options`][api-options], default: `['yaml']`)\n  — configuration\n\n###### Returns\n\nExtension for `micromark` that can be passed in `extensions`, to enable\nfrontmatter syntax ([`Extension`][github-micromark-extension]).\n\n### `frontmatterHtml(options?)`\n\nCreate an extension for `micromark` to support frontmatter when serializing to\nHTML.\n\n\u003e 👉 **Note**: this makes sure nothing is generated in the output HTML for\n\u003e frontmatter.\n\n###### Parameters\n\n* `options` ([`Options`][api-options], default: `['yaml']`)\n  — configuration\n\n###### Returns\n\nExtension for `micromark` that can be passed in `htmlExtensions`, to support\nfrontmatter when serializing to HTML\n([`HtmlExtension`][github-micromark-html-extension]).\n\n### `toMatters(options?)`\n\nSimplify options by normalizing them to an array of matters.\n\n###### Parameters\n\n* `options` ([`Options`][api-options], default: `['yaml']`)\n  — configuration\n\n###### Returns\n\nList of matters ([`Array\u003cMatter\u003e`][api-matter]).\n\n### `Info`\n\nSequence (TypeScript type).\n\nDepending on how this structure is used, it reflects a marker or a fence.\n\n###### Fields\n\n* `open` (`string`)\n  — opening\n* `close` (`string`)\n  — closing\n\n### `Matter`\n\nFields describing a kind of matter (TypeScript type).\n\n\u003e 👉 **Note**: using `anywhere` is a terrible idea.\n\u003e It’s called frontmatter, not matter-in-the-middle or so.\n\u003e This makes your markdown less portable.\n\n\u003e 👉 **Note**: `marker` and `fence` are mutually exclusive.\n\u003e If `marker` is set, `fence` must not be set, and vice versa.\n\n###### Fields\n\n* `type` (`string`)\n  — node type to tokenize as\n* `marker` (`string` or [`Info`][api-info])\n  — character repeated 3 times, used as complete fences\n* `fence` (`string` or [`Info`][api-info])\n  — complete fences\n* `anywhere` (`boolean`, default: `false`)\n  — whether matter can be found anywhere in the document, normally only\n  matter at the start of the document is recognized\n\n### `Options`\n\nConfiguration (TypeScript type).\n\n###### Type\n\n```ts\ntype Options = Array\u003cMatter | Preset\u003e | Matter | Preset\n```\n\n### `Preset`\n\nKnown name of a frontmatter style (TypeScript type).\n\n* `'yaml'` — [`Matter`][api-matter] defined as `{type: 'yaml', marker: '-'}`\n* `'toml'` — [`Matter`][api-matter] defined as `{type: 'toml', marker: '+'}`\n\n###### Type\n\n```ts\ntype Preset = 'toml' | 'yaml'\n```\n\n## Examples\n\nHere are a couple of example of different matter objects and what frontmatter\nthey match.\n\nTo match frontmatter with the same opening and closing fence, namely three of\nthe same markers, use for example `{type: 'yaml', marker: '-'}`, which matches:\n\n```yaml\n---\nkey: value\n---\n```\n\nTo match frontmatter with different opening and closing fences, which each use\nthree different markers, use for example\n`{type: 'custom', marker: {open: '\u003c', close: '\u003e'}}`, which matches:\n\n```text\n\u003c\u003c\u003c\ndata\n\u003e\u003e\u003e\n```\n\nTo match frontmatter with the same opening and closing fences, which both use\nthe same custom string, use for example `{type: 'custom', fence: '+=+=+=+'}`,\nwhich matches:\n\n```text\n+=+=+=+\ndata\n+=+=+=+\n```\n\nTo match frontmatter with different opening and closing fences, which each use\ndifferent custom strings, use for example\n`{type: 'json', fence: {open: '{', close: '}'}}`, which matches:\n\n```json\n{\n  \"key\": \"value\"\n}\n```\n\n## Authoring\n\nWhen authoring markdown with frontmatter, it’s recommended to use YAML\nfrontmatter if possible.\nWhile YAML has some warts, it works in the most places, so using it guarantees\nthe highest chance of portability.\n\nIn certain ecosystems, other flavors are widely used.\nFor example, in the Rust ecosystem, TOML is often used.\nIn such cases, using TOML is an okay choice.\n\nWhen possible, do not use other types of frontmatter, and do not allow\nfrontmatter anywhere.\n\n## HTML\n\nFrontmatter does not relate to HTML elements.\nIt is typically stripped, which is what these extensions do.\n\n## CSS\n\nThis package does not relate to CSS.\n\n## Syntax\n\nFrontmatter forms with the following BNF:\n\n```abnf\nfrontmatter ::= fenceOpen *( eol *line ) eol fenceClose\nfenceOpen ::= sequenceOpen *spaceOrTab\nfenceClose ::= sequenceClose *spaceOrTab\n; Note: options can define custom sequences.\nsequenceOpen ::= 3\"+\" / 3\"-\"\n; Note: options can define custom sequences.\n; Restriction: `sequenceClose` must correspond to `sequenceOpen`.\nsequenceClose ::= 3\"+\" / 3\"-\"\n\n; Character groups for informational purposes.\nbyte ::= %x00-FFFF\nspaceOrTab ::= \"\\t\" / \" \"\neol ::= \"\\n\" / \"\\r\" / \"\\r\\n\"\nline ::= byte - eol\n```\n\nFrontmatter can only occur once.\nIt cannot occur in a container.\nIt must have a closing fence.\nLike flow constructs, it must be followed by an eol (line ending) or\neof (end of file).\n\n## Types\n\nThis package is fully typed with [TypeScript][].\nIt exports the additional types [`Info`][api-info], [`Matter`][api-matter],\n[`Options`][api-options], [`Preset`][api-preset].\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`micromark-extension-frontmatter@^2`, compatible with Node.js 16.\n\nThis package works with `micromark` version `3` and later.\n\n## Security\n\nThis package is safe.\n\n## Related\n\n* [`remark-frontmatter`][github-remark-frontmatter]\n  — remark plugin using this to support frontmatter\n* [`mdast-util-frontmatter`][github-mdast-util-frontmatter]\n  — mdast utility to support frontmatter\n\n## Contribute\n\nSee [`contributing.md` in `micromark/.github`][health-contributing]\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-frontmatter]: #frontmatteroptions\n\n[api-frontmatter-html]: #frontmatterhtmloptions\n\n[api-info]: #info\n\n[api-matter]: #matter\n\n[api-options]: #options\n\n[api-preset]: #preset\n\n[api-to-matters]: #tomattersoptions\n\n[badge-build-image]: https://github.com/micromark/micromark-extension-frontmatter/workflows/main/badge.svg\n\n[badge-build-url]: https://github.com/micromark/micromark-extension-frontmatter/actions\n\n[badge-coverage-image]: https://img.shields.io/codecov/c/github/micromark/micromark-extension-frontmatter.svg\n\n[badge-coverage-url]: https://codecov.io/github/micromark/micromark-extension-frontmatter\n\n[badge-downloads-image]: https://img.shields.io/npm/dm/micromark-extension-frontmatter.svg\n\n[badge-downloads-url]: https://www.npmjs.com/package/micromark-extension-frontmatter\n\n[badge-size-image]: https://img.shields.io/bundlejs/size/micromark-extension-frontmatter\n\n[badge-size-url]: https://bundlejs.com/?q=micromark-extension-frontmatter\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-mdast-util-frontmatter]: https://github.com/syntax-tree/mdast-util-frontmatter\n\n[github-micromark]: https://github.com/micromark/micromark\n\n[github-micromark-extension]: https://github.com/micromark/micromark#syntaxextension\n\n[github-micromark-html-extension]: https://github.com/micromark/micromark#htmlextension\n\n[github-remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter\n\n[health-coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md\n\n[health-contributing]: https://github.com/micromark/.github/blob/main/contributing.md\n\n[health-support]: https://github.com/micromark/.github/blob/main/support.md\n\n[nodejs-condition-development]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions\n\n[npmjs-install]: https://docs.npmjs.com/cli/install\n\n[typescript]: https://www.typescriptlang.org\n\n[wooorm]: https://wooorm.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicromark%2Fmicromark-extension-frontmatter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicromark%2Fmicromark-extension-frontmatter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicromark%2Fmicromark-extension-frontmatter/lists"}