Registry / serialization / hexo-front-matter

hexo-front-matter

library5.0.0jsnpmunverified

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.

serialization web-framework

npm install hexo-front-matter

github ↗package ↗

INSTALL

IMPORT

SIG · HEXO-FRONT-MATTER

hexo-front-matter

serializationjavascriptv5.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse

✓ import { parse } from 'hexo-front-matter';

✗ const parse = require('hexo-front-matter').parse;

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.

stringify

✓ import { stringify } from 'hexo-front-matter';

✗ const stringify = require('hexo-front-matter').stringify;

For ESM, use named import. For CJS, destructure `stringify` directly since v2.0.0.

split

✓ import { split } from 'hexo-front-matter';

Available for splitting YAML front-matter strings without parsing the content. Named import for ESM, destructuring for CJS.

HexoFrontMatter

✓ import type { HexoFrontMatter } from 'hexo-front-matter';

Type definitions are shipped with the package since v4.1.0 and properly built since v4.2.1 for enhanced TypeScript development.

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.

import { parse, stringify } from 'hexo-front-matter'; const contentWithYaml = `--- title: My Awesome Post date: 2023-10-27T10:00:00Z tags: - programming - javascript --- This is the main body of my post. It can contain Markdown or other content. More content here.`; // Parse the content const parsed = parse(contentWithYaml); console.log('Parsed data:', parsed.data); console.log('Parsed content:', parsed.content); // Stringify an object back into front-matter format const dataToSave = { title: 'Another Article', author: 'John Doe', version: 2 }; const contentToSave = 'Hello from the new article body.'; const newFrontMatter = stringify({ data: dataToSave, content: contentToSave }, { prefixSeparator: true }); console.log('\nStringified front-matter:\n', newFrontMatter); const jsonContentWithFrontMatter = ';;;\n"layout": false,\n"title": "Hello world"\n;;;\nLorem ipsum dolor sit amet, consectetur adipiscing elit.'; const parsedJson = parse(jsonContentWithFrontMatter, { mode: 'json' }); console.log('\nParsed JSON front-matter data:', parsedJson.data); console.log('Parsed JSON front-matter content:', parsedJson.content);

Debug

Known issues

breakingStarting 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.

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.

affects: >=5.0.0

gotchaVersion 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.

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.

affects: 4.2.0

breakingVersion 4.0.0 introduced a breaking change by requiring Node.js version 14 or higher. Older Node.js environments will no longer be supported.

fix

Upgrade your Node.js environment to version 14.x or newer to ensure compatibility.

affects: >=4.0.0

breakingVersion 3.0.0 dropped support for Node.js 10.x. Running on unsupported Node.js versions may lead to errors or unexpected behavior.

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+`.

affects: >=3.0.0 <4.0.0

breakingVersion 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`.

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');`.

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: require(...) is not a function

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.

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);`

RangeError: Invalid time value

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.

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.

Error: The Hexo front-matter package requires Node.js version 14 or higher.

Running `hexo-front-matter@4.0.0` or newer with an unsupported Node.js version (e.g., Node.js 12.x or older).

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.

Upgrade

Version history

5.0.0latest on npm

Audit

Dependencies

js-yamlrequiredUsed for parsing and stringifying YAML front-matter. This is a core runtime dependency.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/hexojs/hexo-front-matter ↗

packagehttps://www.npmjs.com/package/hexo-front-matter ↗