{"id":14981446,"url":"https://github.com/josephearl/preliminaries","last_synced_at":"2025-10-02T22:31:29.225Z","repository":{"id":57329782,"uuid":"87591983","full_name":"josephearl/preliminaries","owner":"josephearl","description":"Simple front matter parser that parses YAML, JSON and TOML","archived":false,"fork":true,"pushed_at":"2017-04-16T01:31:04.000Z","size":375,"stargazers_count":7,"open_issues_count":3,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-12-06T21:51:22.474Z","etag":null,"topics":["frontmatter","markdown"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"jonschlinkert/gray-matter","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/josephearl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-04-07T22:37:40.000Z","updated_at":"2020-11-07T04:13:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/josephearl/preliminaries","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josephearl%2Fpreliminaries","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josephearl%2Fpreliminaries/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josephearl%2Fpreliminaries/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josephearl%2Fpreliminaries/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/josephearl","download_url":"https://codeload.github.com/josephearl/preliminaries/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235049009,"owners_count":18927715,"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","markdown"],"created_at":"2024-09-24T14:03:35.387Z","updated_at":"2025-10-02T22:31:28.900Z","avatar_url":"https://github.com/josephearl.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# preliminaries [![Linux Build Status](https://travis-ci.org/josephearl/preliminaries.svg?branch=master)](https://travis-ci.org/josephearl/preliminaries) [![npm version](https://badge.fury.io/js/preliminaries.svg)](https://badge.fury.io/js/preliminaries)\n\nSimple front matter parser for Markdown that supports JSON, YAML, TOML and custom parsers. \n\nNow with [JSON5](http://json5.org) support!\n\nForked from the excellent [jonschlinkert/gray-matter](https://github.com/jonschlinkert/gray-matter), prelimimaries strips things down and makes the YAML and TOML parsers entirely optional, as well as supporting stringifying languages other than YAML.\n\nImproved parsing and auto-detection of languages supports JSON front matter with `{` and `}` plain delimiters and TOML with `+++` delimiters as used in [Hugo](https://gohugo.io).\n\n## Dependency\n\n**npm**\n\n```bash\nnpm install --save preliminaries\n# Optional\nnpm install --save preliminaries-parser-yaml\nnpm install --save preliminaries-parser-toml\nnpm install --save preliminaries-parser-json5\n```\n\n**yarn**\n\n```bash\nyarn add preliminaries\n# Optional\nyarn add preliminaries-parser-yaml\nyarn add preliminaries-parser-toml\nyarn add preliminaries-parser-json5\n```\n\n## Using preliminaries\n\n### `Preliminaries(register: boolean): Preliminaries`\n\nRegisters any default parsers (currently only JSON) for their default languages.\n\n### `PreliminariesParser(register: boolean): PreliminariesParser`\n\nRegisters the parser for it's default language.\n\nLoad preliminaries and some parsers and register the parsers for their default languages:\n\n```bash\nvar preliminaries = require('preliminaries')(true);\nrequire('preliminaries-parser-yaml')(true);\nrequire('preliminaries-parser-toml')(true);\n```\n\nLoad preliminaries and some parsers without registering any parsers:\n\n```bash\nvar preliminaries = require('preliminaries');\nvar tomlParser = require('preliminaries-parser-yaml');\nvar yamlParser = require('preliminaries-parser-toml');\n```\n\n### `Preliminaries.parse(str: string, options?: PreliminariesOptions): any`\n\nParse some JSON front matter:\n\n```js\npreliminaries.parse('{\\n\"name\":\"Joseph\"\\n}\\nContent')\n// Returns\n{\n  data: {name: 'Joseph'},\n  content: 'Content'\n}\n```\n\nor YAML:\n\n```js\npreliminaries.parse('---\\nname: Joseph\\n---\\nContent')\n// Returns\n{\n  data: {name: 'Joseph'},\n  content: 'Content'\n}\n```\n\nand even TOML:\n\n```js\npreliminaries.parse('+++\\nname = \"Joseph\"\\n+++\\nContent')\n// Returns\n{\n  data: {name: 'Joseph'},\n  content: 'Content'\n}\n```\n\nIt can automatically detect any language embedded after the first delimiter such as `---yaml` or `---json`, as well standard delimiters for languages such as `+++` for TOML or `{` and `}` for JSON.\n\nUse custom delimiters:\n\n```js\npreliminaries.parse('~~~\\nname: Joseph\\n~~~\\nContent', {lang: 'yaml', delims: '~~~'})\n// Returns\n{\n  data: {name: 'Joseph'},\n  content: 'Content'\n}\n```\n\nwith JSON as well!\n\n```js\npreliminaries.parse('~~~\\n{\\n\"name\":\"Joseph\"\\n}\\n~~~\\nContent', {lang: 'json', delims: '~~~'})\n// Returns\n{\n  data: {name: 'Joseph'},\n  content: 'Content'\n}\n```\n\n### `Preliminaries.stringify(str: string, data: Object, options?: PreliminariesOptions): string`\n\nStringify a content string and front matter JavaScript object:\n\n```js\npreliminaries.stringify('Content', {name: 'Joseph'})\n// Returns\n---json\n{\n\"name\":\"Joseph\"\n}\n---\nContent\n```\n\nwith standard JSON delimiters:\n\n```js\npreliminaries.stringify('Content', {name: 'Joseph'}, {stringifyUseParserDelims: true})\n// Returns\n{\n\"name\":\"Joseph\"\n}\nContent\n```\n\nor YAML front matter:\n\n```js\npreliminaries.stringify('Content', {name: 'Joseph'}, {lang: 'yaml', stringifyUseParserDelims: true})\n// Returns\n---\nname: Joseph\n---\nContent\n```\n\nStringify with custom delimiters:\n\n```js\npreliminaries.stringify('Content', {name: 'Joseph'}, {lang: 'yaml', delims: '~~~'})\n// Returns\n~~~\nname: Joseph\n~~~\nContent\n```\n\n### `Preliminaries.test(str: string, options?: PreliminariesOptions): boolean`\n\nTest whether a string contains front matter of any kind:\n\n```\npreliminaries.test('{\\n\"abc\": \"xyz\"\\n}');\npreliminaries.test('---\\nabc: xyz\\n---');\npreliminaries.test('+++\\nabc = \"xyz\"\\n+++');\npreliminaries.test('~~~\\nabc = \"xyz\"\\n~~~');\n// All return true\n```\n\nor front matter with particular delimiters:\n\n```\npreliminaries.test('---\\nabc: xyz\\n---', {delims: '~~~'});\n// Returns false\n```\n\n### `Preliminaries.register(lang: string | string[], parser: PreliminariesParser): void`\n\nRegister a parser for a new language:\n\n```js\npreliminaries.register('xml', xmlParser);\n```\n\nfor this to succeed no parser must be already registered for the language, **and** the opening delimiters of the parser must not match the opening delimiters of *any* parser currently registered (this would lead to ambiguous auto-detection of languages).\n\nAn error will be thrown if either of the above conditions are false. You can check if a parser can be registered with `Preliminaries.registerable`.\n\n### `Preliminaries.unregister(lang: string | string[]): void`\n\nUnregister a previously registered parser:\n\n```js\npreliminaries.unregister('json');\n```\n\n### `Preliminaries.registerable(lang: string | string[], parser: PreliminariesParser): boolean`\n\nCheck if a parser can be registered for the language, or all languages if an array -- this returns `false if a parser is already registered for any of the languages, or if the opening delimiters of this parser match those of an already existing parser:\n\n```js\npreliminaries.registerable('---', parser: myParser);\n```\n\nif this call returns `true`, a subsequent call to `Preliminaries.register` will succeed without error.\n\n### `Preliminaries.registered(lang: string | string[]): boolean`\n\nCheck if a parser is registered for a language:\n\n```js\npreliminaries.registered('json');\n```\n\nor if one is registered for *any* of the languages:\n\n```js\npreliminaries.registered(['json', 'yaml', 'toml']);\n```\n\n**Note:** a `false` result does not indicate a parser may be registered without error, just that one is not already registered for this language; use `Preliminaries.registerable` for that purpose.\n\n### `Preliminaries.jsonParser: PreliminariesParser`\n\nThe default JSON parser. Use it to register it for another language:\n\n```js\nvar preliminaries = require('preliminaries');\npreliminaries.register('xyz', preliminaries.jsonParser)\npreliminaries.parse('---xyz\\n{\\n\"name\":\"Joseph\"\\n}\\n---\\nContent')\n// Returns\n{\n  data: {name: 'Joseph'},\n  content: 'Content'\n}\n```\n\n## Options\n\n### `PreliminariesOptions.parser?: PreliminariesParser`\n\nOptionally provide a custom parser to use when parsing or stringifying.\n\n### `PreliminariesOptions.lang?: string`\n\nThe language the front matter is in. \n\nRequired when parsing if using custom delimiters or whenever stringifying to language other than JSON. \n\n### `PreliminariesOptions.delims?: string | string[]`\n\nCustom delimiters.\n\nA string (if start and end delimiters are the same), or an array of 2 elements containing the start and end delimiters.\n\n### `PreliminariesOptions.stringifyIncludeLang?: boolean`\n\nWhether to output the front matter language the first delimiter.\n\nIf not set the language will be output when stringifying if a custom delimiters are not set with `PreliminariesOptions.delims` and `PreliminariesOptions.stringifyUseParserDelims` is not truthy.\n\n### `PreliminariesOptions.stringifyUseParserDelims?: boolean`\n\nWhether to stringify using the default delimiters defined by the parser for the language, instead of the default `---lang` format.\n\n## Creating parsers\n\nYour parser should include `preliminaries` as a `peerDependency` in your package.json.\n\n### `PreliminariesParser(register: boolean): PreliminariesParser`\n\nThe root export of your parser should be a function that accepts a `boolean` value, if `truthy` you should register your parser for it's default language:\n\n```js\nvar preliminaries = require('preliminaries');\n\nvar myParser = function(register) {\n  if (register) {\n    preliminaries.register('abc', myParser);\n  }\n}\n\nmodule.exports = myParser;\n```\n\n### `PreliminariesParser.parse(str: string, options?: PreliminariesOptions): any`\n\nParse a front matter string without delimiters into a JavaScript object.\n\n```\nmyParser.parse = function(str, options) {\n  return {};\n}\n```\n\n### `PreliminariesParser.stringify(data: Object, options?: PreliminariesOptions): string`\n\nStringify a JavaScript front matter object into string without delimiters.\n\n```\nmyParser.stringify = function(data, options) {\n  return '';\n}\n```\n\n### `PreliminariesParser.delims?: string | string[]`\n\nThe default delimiters for the parser, used to auto-detect the language and parser to use and when `stringify`ing with the `stringifyUseParserDelims` option.\n\nA string (if start and end delimiters are the same), or an array of 2 elements containing the start and end delimiters.\n\n```js\nmyParser.delims = ['\u003c', '\u003e'];\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosephearl%2Fpreliminaries","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjosephearl%2Fpreliminaries","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosephearl%2Fpreliminaries/lists"}