carvematter

An opinionated frontmatter parser and serializer focused on linting and formatting for Obsidian markdown notes.

Works both as CLI and JS/TS library.

Installation

npm install carvematter
# or
pnpm add carvematter
# or
yarn add carvematter

Quick Start

import { parse, serialize, lint, format } from 'carvematter';
import { read, write, merge } from 'carvematter/fs';

// Parse frontmatter
const content = `---
title: Hello World
date: 2024-01-01
---
Body content`;

const result = parse(content);
console.log(result.data); // { title: 'Hello World', date: '2024-01-01' }

// Serialize to YAML
const yaml = serialize({ title: 'New Post', draft: true });

// Lint frontmatter
const lintResult = lint(result.data, {
  'carvematter/sort-fields': {
    key: 'carvematter/sort-fields',
    severity: 'warning',
    options: { order: ['title', 'date'] },
  },
});

// Format (auto-fix)
const formatted = format(result.data, {
  'carvematter/sort-fields': {
    key: 'carvematter/sort-fields',
    severity: 'warning',
    options: { order: ['title', 'date'] },
  },
});

API Reference

Core Functions

parse<T>(content: string): ParseResult<T>

Parse frontmatter from content string.

const result = parse(`---
title: Hello
---
Body`);
// Returns: { data: { title: 'Hello' }, body: 'Body', hasFrontmatter: true, ... }

serialize<TData>(data: TData): string

Convert JavaScript object to YAML frontmatter string.

const yaml = serialize({ title: 'Hello', tags: ['js', 'ts'] });
// Returns: "title: Hello\ntags:\n  - js\n  - ts"

lint<TData>(data: TData, rules?: Rules): LintResult

Validate frontmatter against rules.

const result = lint(data, {
  'carvematter/schema-validation': {
    key: 'carvematter/schema-validation',
    severity: 'error',
    options: { schema: myZodSchema },
  },
});
// Returns: { errors: [], warnings: [], valid: true, fixable: false }

format<TData>(data: TData, rules: Rules): TData

Auto-fix frontmatter issues based on rules.

const fixed = format(data, {
  'carvematter/sort-fields': {
    key: 'carvematter/sort-fields',
    severity: 'warning',
    options: { order: ['title', 'date'] },
  },
});

File Operations (carvematter/fs)

read<T>(path: string): Promise<T | null>

Read frontmatter from a file.

import { read } from 'carvematter/fs';

const data = await read('./post.md');

write<T>(path: string, data: T): Promise<void>

Write frontmatter to a file (preserves body).

import { write } from 'carvematter/fs';

await write('./post.md', { title: 'New Title', date: '2024-01-01' });

merge<T>(source: string, data: T, target?: string): Promise<void>

Merge data into existing frontmatter.

import { merge } from 'carvematter/fs';

await merge('./post.md', { tags: ['new'] });

CLI Usage

Install globally:

npm install -g carvematter

Or use with npx:

npx carvematter lint "content/**/*.md"

Commands

carvematter lint <files...>

Lint files and report issues.

carvematter lint "content/**/*.md" "posts/**/*.md"

carvematter format <files...>

Auto-fix frontmatter issues.

carvematter format "content/**/*.md"

carvematter check <files...>

Check files without modifying (useful for CI).

carvematter check "content/**/*.md"

Configuration

Create a .carvematterrc file (JSON or YAML) in your project root:

# .carvematterrc
rules:
  carvematter/sort-fields:
    severity: warning
    options:
      order: [title, date, tags, draft]
  carvematter/schema-validation:
    severity: error
    options:
      schema: ./frontmatter.schema.js  # or .ts (will try .js automatically)

include:
  - "content/**/*.md"
  - "posts/**/*.md"

exclude:
  - "**/drafts/**"

The CLI searches for config files in this order:

1. .carvematterrc (JSON or YAML)
2. .carvematterrc.json
3. .carvematterrc.yaml
4. carvematter.config.js

Built-in Rules

carvematter/sort-fields

Ensures fields are sorted according to a specified order.

{
  key: 'carvematter/sort-fields',
  severity: 'warning',
  options: {
    order: ['title', 'date', 'tags'],
  },
}

Fixable: Yes

carvematter/schema-validation

Validates frontmatter against a Zod schema. The schema can be provided directly or as a path to a file that exports a Zod schema.

In code:

import { z } from 'zod';

const schema = z.object({
  title: z.string(),
  date: z.string(),
  tags: z.array(z.string()).optional(),
});

{
  key: 'carvematter/schema-validation',
  severity: 'error',
  options: {
    schema,
  },
}

In config file (.carvematterrc):

You can provide schemas in four ways:

1. Zod schema file (.js, .mjs, .cjs):

rules:
  carvematter/schema-validation:
    severity: error
    options:
      schema: ./frontmatter.schema.js

The schema file should export a Zod schema:

// frontmatter.schema.js
import { z } from 'zod';

export default z.object({
  title: z.string(),
  date: z.string(),
});

2. JSON Schema file (.json):

rules:
  carvematter/schema-validation:
    severity: error
    options:
      schema: ./frontmatter.schema.json

// frontmatter.schema.json
{
  "type": "object",
  "properties": {
    "title": { "type": "string" },
    "date": { "type": "string" }
  },
  "required": ["title"]
}

3. JSON Schema from URL:

rules:
  carvematter/schema-validation:
    severity: error
    options:
      schema: https://raw.githubusercontent.com/aitorllj93/segha/refs/heads/main/schemas/catalog/json-schemas/es/NoteSchema.json

The URL should point to a JSON Schema file that will be fetched and converted to Zod.

4. Inline JSON Schema object:

rules:
  carvematter/schema-validation:
    severity: error
    options:
      schema:
        type: object
        properties:
          title:
            type: string
          date:
            type: string
        required:
          - title

Supported file extensions: .js, .mjs, .cjs, .json

Note:

• If you specify a .ts file path, the loader will automatically try the corresponding .js file (assuming the TypeScript file has been transpiled).
• JSON Schemas (from files, URLs, or inline) are automatically converted to Zod schemas using z.fromJSONSchema().

Fixable: No

Types

import type {
  ParseResult,
  LintResult,
  Rules,
  RuleKey,
  RuleConfig,
  RuleMessage,
  Rule,
} from 'carvematter';

License

ISC