{"id":13941933,"url":"https://github.com/vfile/vfile-matter","last_synced_at":"2025-06-11T21:40:14.484Z","repository":{"id":36463086,"uuid":"225412368","full_name":"vfile/vfile-matter","owner":"vfile","description":"utility to parse the YAML front matter in a vfile","archived":false,"fork":false,"pushed_at":"2025-03-19T14:26:01.000Z","size":87,"stargazers_count":32,"open_issues_count":0,"forks_count":4,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-06-01T07:44:11.447Z","etag":null,"topics":["file","frontmatter","matter","vfile","vfile-util","virtual","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/vfile.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,"zenodo":null},"funding":{"github":"unifiedjs","open_collective":"unified"}},"created_at":"2019-12-02T15:49:42.000Z","updated_at":"2025-04-15T18:20:03.000Z","dependencies_parsed_at":"2024-06-18T15:28:45.421Z","dependency_job_id":"44461d82-5009-4f4a-ba61-fed22776cccc","html_url":"https://github.com/vfile/vfile-matter","commit_stats":{"total_commits":58,"total_committers":6,"mean_commits":9.666666666666666,"dds":0.08620689655172409,"last_synced_commit":"85a5b9e717c1e9c8388bfe07259622ae21ca2418"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/vfile/vfile-matter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vfile%2Fvfile-matter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vfile%2Fvfile-matter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vfile%2Fvfile-matter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vfile%2Fvfile-matter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vfile","download_url":"https://codeload.github.com/vfile/vfile-matter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vfile%2Fvfile-matter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259331958,"owners_count":22841977,"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":["file","frontmatter","matter","vfile","vfile-util","virtual","yaml"],"created_at":"2024-08-08T02:01:36.560Z","updated_at":"2025-06-11T21:40:14.471Z","avatar_url":"https://github.com/vfile.png","language":"JavaScript","funding_links":["https://github.com/sponsors/unifiedjs","https://opencollective.com/unified"],"categories":["JavaScript"],"sub_categories":[],"readme":"# vfile-matter\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[vfile][github-vfile] utility parse YAML front matter.\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  * [`matter(file[, options])`](#matterfile-options)\n  * [`Options`](#options)\n  * [`YamlOptions`](#yamloptions)\n* [Types](#types)\n* [Compatibility](#compatibility)\n* [Contribute](#contribute)\n* [License](#license)\n\n## What is this?\n\nThis package parses YAML frontmatter,\nwhen found in a file,\nand exposes it as `file.data.matter`.\nIt can optionally strip the frontmatter,\nwhich is useful for languages that do not understand frontmatter,\nbut stripping can make it harder to deal with languages that *do* understand it,\nsuch as markdown,\nbecause it messes up positional info of warnings and errors.\n\n## When should I use this?\n\nFrontmatter is a metadata format in front of content.\nIt’s typically written in YAML and is often used with markdown.\nThis mechanism works well when you want authors,\nthat have some markup experience,\nto configure where or how the content is displayed or supply metadata about\ncontent.\n\nWhen using vfiles with markdown,\nyou are likely also using [remark][github-remark],\nin which case you should use [`remark-frontmatter`][github-remark-frontmatter],\ninstead of\nstripping frontmatter.\n\n## Install\n\nThis package is [ESM only][github-gist-esm].\nIn Node.js (version 16+),\ninstall with [npm][npmjs-install]:\n\n```sh\nnpm install vfile-matter\n```\n\nIn Deno with [`esm.sh`][esmsh]:\n\n```js\nimport {matter} from 'https://esm.sh/vfile-matter@5'\n```\n\nIn browsers with [`esm.sh`][esmsh]:\n\n```html\n\u003cscript type=\"module\"\u003e\n  import {matter} from 'https://esm.sh/vfile-matter@5?bundle'\n\u003c/script\u003e\n```\n\n## Use\n\nSay our document `example.html` contains:\n\n```html\n---\nlayout: solar-system\n---\n\u003ch1\u003eJupiter\u003c/h1\u003e\n```\n\n…and our module `example.js` looks as follows:\n\n```js\nimport {read} from 'to-vfile'\nimport {matter} from 'vfile-matter'\n\nconst file = await read('example.html')\n\nmatter(file, {strip: true})\n\nconsole.log(file.data)\nconsole.log(String(file))\n```\n\n…now running `node example.js` yields:\n\n```js\n{ matter: { layout: 'solar-system' } }\n```\n\n```html\n\u003ch1\u003eJupiter\u003c/h1\u003e\n```\n\n## API\n\nThis package exports the identifier [`matter`][api-matter].\nIt exports the [TypeScript][] types\n[`Options`][api-options] and\n[`YamlOptions`][api-yaml-options].\nThere is no default export.\n\n### `matter(file[, options])`\n\nParse the YAML front matter in a file and expose it as `file.data.matter`.\n\nIf no matter is found in the file,\nnothing happens,\nexcept that `file.data.matter` is set to an empty object (`{}`).\n\nIf the file value is an `Uint8Array`,\nassumes it is encoded in UTF-8.\n\n###### Parameters\n\n* `file`\n  ([`VFile`][github-vfile])\n  — virtual file\n* `options`\n  ([`Options`][api-options], default: `{}`)\n  — configuration\n\n###### Returns\n\nNothing (`undefined`).\n\n### `Options`\n\nConfiguration (TypeScript type).\n\n###### Fields\n\n* `strip`\n  (`boolean`, default: `false`)\n  — remove the YAML front matter from the file\n* `yaml`\n  ([`YamlOptions`][api-yaml-options], default: `{}`)\n  — configuration for the YAML parser,\n  passed to [`yaml`][github-yaml] as `x` in `yaml.parse('', x)`\n\n### `YamlOptions`\n\nOptions for the YAML parser (TypeScript type).\n\nEquivalent to the combination of\n[`DocumentOptions`](https://eemeli.org/yaml/#document-options),\n[`ParseOptions`](https://eemeli.org/yaml/#parse-options),\n[`SchemaOptions`](https://eemeli.org/yaml/#schema-options),\nand\n[`ToJsOptions`](https://eemeli.org/yaml/#tojs-options).\n\n###### Type\n\n```ts\ntype YamlOptions = DocumentOptions \u0026\n  ParseOptions \u0026\n  SchemaOptions \u0026\n  ToJsOptions\n```\n\n## Types\n\nTo type `file.data.matter` with [TypeScript][],\nyou can augment `DataMap` from `vfile` as follows:\n\n```ts\ndeclare module 'vfile' {\n  interface DataMap {\n    matter: {\n      // `file.data.matter.string` is typed as `string | undefined`.\n      title?: string | undefined\n    }\n  }\n}\n\n// You may not need this,\n// but it makes sure the file is a module.\nexport {}\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,\nwe drop support for unmaintained versions of Node.\nThis means we try to keep the current release line,\n`vfile-matter@5`,\ncompatible with Node.js 16.\n\n## Contribute\n\nSee [`contributing.md`][health-contributing] in [`vfile/.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,\norganization,\nor community you agree to abide by its terms.\n\n## License\n\n[MIT][file-license] © [Titus Wormer][wooorm]\n\n\u003c!-- Definitions --\u003e\n\n[api-matter]: #matterfile-options\n\n[api-options]: #options\n\n[api-yaml-options]: #yamloptions\n\n[badge-build-image]: https://github.com/vfile/vfile-matter/workflows/main/badge.svg\n\n[badge-build-url]: https://github.com/vfile/vfile-matter/actions\n\n[badge-coverage-image]: https://img.shields.io/codecov/c/github/vfile/vfile-matter.svg\n\n[badge-coverage-url]: https://codecov.io/github/vfile/vfile-matter\n\n[badge-downloads-image]: https://img.shields.io/npm/dm/vfile-matter.svg\n\n[badge-downloads-url]: https://www.npmjs.com/package/vfile-matter\n\n[badge-size-image]: https://img.shields.io/bundlejs/size/vfile-matter\n\n[badge-size-url]: https://bundlejs.com/?q=vfile-matter\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-remark]: https://github.com/remarkjs/remark\n\n[github-remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter\n\n[github-vfile]: https://github.com/vfile/vfile\n\n[github-yaml]: https://github.com/eemeli/yaml\n\n[health]: https://github.com/vfile/.github\n\n[health-coc]: https://github.com/vfile/.github/blob/main/code-of-conduct.md\n\n[health-contributing]: https://github.com/vfile/.github/blob/main/contributing.md\n\n[health-support]: https://github.com/vfile/.github/blob/main/support.md\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%2Fvfile%2Fvfile-matter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvfile%2Fvfile-matter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvfile%2Fvfile-matter/lists"}