frontmatter

This module provides utility functions for processing and managing YAML front matter in Obsidian notes.

Interfaces

Interface	Description
ObsidianFrontmatter	A front matter of an Obsidian file.
ObsidianPublishFrontmatter	A front matter for publishing in Obsidian.
RemoveEmptyFrontmatterValuesParams	Parameters for removeEmptyFrontmatterValues.

Functions

Function	Description
checkIsPlainObject	Checks whether the value is a plain object, i.e. an object literal rather than an array or a class instance. `parseYaml()` turns a YAML timestamp into a `Date`, which has no own enumerable properties, so a plain `typeof value === 'object'` test would report every date as an empty object.
parseFrontmatter	Parses the front matter of a given content string.
registerFrontmatterFormattingPreserver	Registers the FrontmatterFormattingPreserver every front-matter write in this library routes through. There is at most one, shared by every plugin loaded in the same realm — like every other registration in this library it lives in the `globalThis.__obsidianDevUtils` bag — so a single call makes every write this library performs formatting-preserving, `processFrontmatter()` and `applyFileChanges()` included. Pass `null` to unregister. The preserver is NOT registered by default, and that is a bundle-size decision rather than a doubt about the engine: the one this library ships needs the `yaml` package’s CST API, which Obsidian does not hand to plugins and which costs about 100 KB of a plugin’s `main.js`. A plugin that wants it calls `enableFrontmatterFormattingPreservation()` from `@mnaoumov/obsidian-lib/frontmatter-formatting`, and pays for it only then.
removeEmptyFrontmatterValues	Removes the empty values from a front matter object, at any nesting depth. By default only empty strings are removed — both as property values and as array items. `null`, `undefined`, empty arrays and empty objects are kept unless the corresponding option is enabled. The object is modified in place, so the function can be called straight from a `processFrontmatter()` callback.
setFrontmatter	Sets the front matter of a given content string. When a FrontmatterFormattingPreserver is registered (see registerFrontmatterFormattingPreserver) the write goes through it first, so the parts of the block the change does not reach keep the bytes their author wrote — their comments, quoting, blank lines and indentation. Without one, and whenever the preserver reports it cannot be faithful, the whole block is parsed and written out again, which is what Obsidian’s own `processFrontMatter()` does.

Types

Type Description

CombinedFrontmatter A combined front matter of a document. It is a union of custom front matter, Obsidian front matter, and additional properties.

FrontmatterFormattingPreserver A rewrite of a note’s front matter that keeps the author’s original formatting wherever the change does not reach it. It is handed the whole note and the front matter to write, and returns the whole new note — or null when it cannot be faithful, which hands the write back to setFrontmatter’s own parse-and-stringify path. Returning null is never an error: it is how the preserver guarantees it can only ever match or improve on that path, never do worse than it.

Type	Description
CombinedFrontmatter	A combined front matter of a document. It is a union of custom front matter, Obsidian front matter, and additional properties.
FrontmatterFormattingPreserver	A rewrite of a note’s front matter that keeps the author’s original formatting wherever the change does not reach it. It is handed the whole note and the front matter to write, and returns the whole new note — or `null` when it cannot be faithful, which hands the write back to setFrontmatter’s own parse-and-stringify path. Returning `null` is never an error: it is how the preserver guarantees it can only ever match or improve on that path, never do worse than it.