Frontmatter Transformer

Safe bulk frontmatter transformations through namespaced CLI commands. The plugin reuses the existing Content Migration planner, mutation journal, history, and rollback; it does not implement a separate migration engine.

日本語

Overview

import { defineConfig } from "@riebeckite/core";
import { frontmatterTransformer } from "@riebeckite/plugin-frontmatter-transformer";
 
export default defineConfig({
  // ...
  plugins: [frontmatterTransformer()],
});

The plugin adds the frontmatter command namespace. Every command requires a project and discovers the content root from the resolved configuration.

riebeckite frontmatter presets
riebeckite frontmatter plan --preset normalize-tags
riebeckite frontmatter apply --preset normalize-tags --apply
riebeckite frontmatter history
riebeckite frontmatter rollback <plan-id> --apply

plan and apply are dry runs unless --apply is passed. apply without --apply prints the same plan summary without writing files. Repeat --preset to combine presets in one plan.

Before and after

Given this frontmatter:

---
title: "  Writing guide  "
tags: "#guides, setup, guides"
description: "  "
---

run:

riebeckite frontmatter apply --preset normalize-tags --preset trim-text

The plan reports one changed file. Re-run with --apply to write it:

riebeckite frontmatter apply --preset normalize-tags --preset trim-text --apply

The result is:

---
title: Writing guide
tags:
  - guides
  - setup
---

normalize-tags removes the leading #, splits on commas, and removes duplicates. trim-text trims title and removes the empty description. YAML key order and formatting may change when the file is rewritten.

Example plan output (the plan ID varies):

Migration plan <plan-id>
Presets: normalize-tags@1, trim-text@1
Changed files: 1
Created: 0, moved: 0, frontmatter: 1

Example apply output (the journal path varies):

Applied 1 file change(s); mutation journal .riebeckite/migrations/<plan-id>/journal.json.

Presets

A preset is a versioned Content Migration definition. It is resolved through the same registry and planner as project migrations. Unknown preset names fail before any file is read or written.

Commands

plan accepts --out <path> to save the plan. apply accepts --plan <path> to use a saved plan; the engine re-plans and rejects a stale plan if the content or preset definitions changed. history accepts --limit. Commands return JSON when --json is passed.

State and safety

Plans, state, history, and mutation journals live under the content directory's .riebeckite/migrations by default. Writes use the existing FileSystem content mutation pipeline: path validation, symlink checks, atomic writes, a lock file, SHA-256 fingerprints, backups, and recovery of interrupted runs. Rollback restores the journal backups for the selected plan.

Nothing is deleted automatically outside the selected preset fields. Review a plan before applying it, especially when combining presets.

Related

• CLI extension
• Content migrations
• Plugin system