{"id":13295,"library":"hexo-front-matter","title":"Hexo Front-Matter Parser","description":"hexo-front-matter is a JavaScript library dedicated to parsing and stringifying front-matter data, supporting both YAML and JSON formats. It is a fundamental component within the Hexo static site generator ecosystem but is designed for standalone use for general front-matter processing needs. The current stable version is 5.0.0, published approximately 5 months ago. The package maintains an active development cycle, with major versions frequently released to align with Node.js LTS updates, or to introduce significant internal refactors and bug fixes, such as the critical change to timezone handling introduced in v5.0.0. Key differentiators include its versatile support for both YAML and JSON front-matter, flexible options for prefixing separators, and a clear API for parsing, stringifying, splitting, and escaping front-matter sections, making it a robust solution for various content management or static site generation workflows.","status":"active","version":"5.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/hexojs/hexo-front-matter","tags":["javascript","front-matter","front matter","yaml","yml","hexo","json","typescript"],"install":[{"cmd":"npm install hexo-front-matter","lang":"bash","label":"npm"},{"cmd":"yarn add hexo-front-matter","lang":"bash","label":"yarn"},{"cmd":"pnpm add hexo-front-matter","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for parsing and stringifying YAML front-matter. This is a core runtime dependency.","package":"js-yaml","optional":false}],"imports":[{"note":"For ESM, use named import. For CJS, destructure `parse` directly since v2.0.0. Before v2.0.0, the default export was the parse function.","wrong":"const parse = require('hexo-front-matter').parse;","symbol":"parse","correct":"import { parse } from 'hexo-front-matter';"},{"note":"For ESM, use named import. For CJS, destructure `stringify` directly since v2.0.0.","wrong":"const stringify = require('hexo-front-matter').stringify;","symbol":"stringify","correct":"import { stringify } from 'hexo-front-matter';"},{"note":"Available for splitting YAML front-matter strings without parsing the content. Named import for ESM, destructuring for CJS.","symbol":"split","correct":"import { split } from 'hexo-front-matter';"},{"note":"Type definitions are shipped with the package since v4.1.0 and properly built since v4.2.1 for enhanced TypeScript development.","symbol":"HexoFrontMatter","correct":"import type { HexoFrontMatter } from 'hexo-front-matter';"}],"quickstart":{"code":"import { parse, stringify } from 'hexo-front-matter';\n\nconst contentWithYaml = `---\ntitle: My Awesome Post\ndate: 2023-10-27T10:00:00Z\ntags:\n  - programming\n  - javascript\n---\n\nThis is the main body of my post. It can contain Markdown or other content.\n\nMore content here.`;\n\n// Parse the content\nconst parsed = parse(contentWithYaml);\nconsole.log('Parsed data:', parsed.data);\nconsole.log('Parsed content:', parsed.content);\n\n// Stringify an object back into front-matter format\nconst dataToSave = {\n  title: 'Another Article',\n  author: 'John Doe',\n  version: 2\n};\nconst contentToSave = 'Hello from the new article body.';\n\nconst newFrontMatter = stringify({ data: dataToSave, content: contentToSave }, { prefixSeparator: true });\nconsole.log('\\nStringified front-matter:\\n', newFrontMatter);\n\nconst jsonContentWithFrontMatter = ';;;\\n\"layout\": false,\\n\"title\": \"Hello world\"\\n;;;\\nLorem ipsum dolor sit amet, consectetur adipiscing elit.';\nconst parsedJson = parse(jsonContentWithFrontMatter, { mode: 'json' });\nconsole.log('\\nParsed JSON front-matter data:', parsedJson.data);\nconsole.log('Parsed JSON front-matter content:', parsedJson.content);","lang":"typescript","description":"This example demonstrates how to parse both YAML and JSON front-matter from a string and how to stringify an object back into a front-matter formatted string."},"warnings":[{"fix":"Review the official documentation on timezone behavior for v5.x and adjust your `defaultTimeZone` configuration or date handling logic if necessary. Ensure timestamps either include timezone information or are handled consistently with the new default behavior.","message":"Starting from v5.0.0, timezone handling has been changed, specifically impacting how timestamps in front-matter without explicit timezone information are interpreted relative to a `defaultTimeZone` option. Developers relying on specific date interpretations should review the new behavior to avoid discrepancies.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Avoid `hexo-front-matter@4.2.0` and upgrade directly to `hexo-front-matter@4.2.1` or newer to ensure correct TypeScript type definitions are available.","message":"Version 4.2.0 was published without proper TypeScript build artifacts, leading to potential type errors or missing declarations for TypeScript users. This was quickly addressed in a subsequent patch release.","severity":"gotcha","affected_versions":"4.2.0"},{"fix":"Upgrade your Node.js environment to version 14.x or newer to ensure compatibility.","message":"Version 4.0.0 introduced a breaking change by requiring Node.js version 14 or higher. Older Node.js environments will no longer be supported.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure your Node.js environment is version 12.x or higher, but less than 14.x, if you need to remain on a 3.x release. For current usage, upgrade to Node.js 14+ and `hexo-front-matter@4.0.0+`.","message":"Version 3.0.0 dropped support for Node.js 10.x. Running on unsupported Node.js versions may lead to errors or unexpected behavior.","severity":"breaking","affected_versions":">=3.0.0 <4.0.0"},{"fix":"Update your CommonJS `require` statements from `const yfm = require('hexo-front-matter');` to `const { parse: yfm } = require('hexo-front-matter');` or `const { parse, stringify } = require('hexo-front-matter');`.","message":"Version 2.0.0 changed the CommonJS import pattern. Previously, `require('hexo-front-matter')` would directly return the `parse` function. From v2.0.0 onwards, it returns an object containing named exports like `parse` and `stringify`.","severity":"breaking","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Adjust the CommonJS import to destructure the `parse` function: `const { parse } = require('hexo-front-matter'); parse(str);` or `const yfm = require('hexo-front-matter').parse; yfm(str);`","cause":"Attempting to use `const yfm = require('hexo-front-matter'); yfm(str);` on versions 2.0.0 or later, where `require` no longer returns the `parse` function directly but an object of named exports.","error":"TypeError: require(...) is not a function"},{"fix":"Review your date formats in front-matter and ensure they include explicit timezone information (e.g., `2023-10-27T10:00:00Z`). Alternatively, configure the `defaultTimeZone` option when calling `parse()` to match your expected behavior.","cause":"After upgrading to v5.0.0, date strings in front-matter that previously worked might be parsed incorrectly if they relied on specific timezone interpretations that changed with the v5.0.0 update, especially without explicit timezone information or a `defaultTimeZone` option.","error":"RangeError: Invalid time value"},{"fix":"Upgrade your Node.js environment to version 14.15.0 or higher. The package specifies `>=20.19.0` for v5.0.0, so updating to the latest LTS Node.js is recommended.","cause":"Running `hexo-front-matter@4.0.0` or newer with an unsupported Node.js version (e.g., Node.js 12.x or older).","error":"Error: The Hexo front-matter package requires Node.js version 14 or higher."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}