Front-matter Processing

/**
 * Configure front-matter parsing options
 * @param options - Boolean to enable/disable or gray-matter options object
 * @returns Metalsmith instance for chaining
 */
frontmatter(options: boolean | GrayMatterOptions): Metalsmith;

/**
 * Get current front-matter configuration
 * @returns Current front-matter settings
 */
frontmatter(): boolean | GrayMatterOptions;

interface GrayMatterOptions {
  /** Front-matter language: "yaml", "json", "toml", etc. (default: "yaml") */
  language?: string;
  /** Enable excerpt parsing or provide custom excerpt function */
  excerpt?: boolean | ((file: GrayMatterFile<string>, options: GrayMatterOptions) => any);
  /** Separator for excerpt content (default: "---") */
  excerpt_separator?: string;
  /** Front-matter delimiters (default: "---") */
  delimiters?: string | string[];
  /** Custom parsing engines for different formats */
  engines?: {
    [engine: string]: ((file: string) => any) | {
      parse: (file: string) => any;
      stringify?: (data: any) => string;
    };
  };
}

import Metalsmith from "metalsmith";

// Enable front-matter with default settings
metalsmith.frontmatter(true);

// Disable front-matter parsing
metalsmith.frontmatter(false);

// Custom front-matter configuration
metalsmith.frontmatter({
  excerpt: true,
  excerpt_separator: '<!-- more -->',
  language: 'yaml',
  delimiters: '---'
});

// JSON front-matter
metalsmith.frontmatter({
  language: 'json',
  delimiters: [';;;', ';;;']
});

/**
 * Front-matter parser instance (available as metalsmith.matter)
 */
interface Matter {
  /** Parse string or buffer for front-matter */
  parse(contents: Buffer | string): File;
  /** Stringify file object back to front-matter format */
  stringify(file: File): string;
  /** Get or set parser options */
  options(options?: GrayMatterOptions): GrayMatterOptions | void;
  /** Wrap data with front-matter delimiters */
  wrap(data: string): string;
}

/**
 * Parse front-matter from content
 * @param contents - String or Buffer containing front-matter and content
 * @returns File object with parsed metadata and contents
 */
matter.parse(contents: Buffer | string): File;

const metalsmith = Metalsmith(__dirname);

// Parse front-matter manually
const fileContent = `---
title: My Article
date: 2024-01-01
tags: [javascript, metalsmith]
excerpt: This is a preview
---
<!-- more -->
# Article Content

This is the main content of the article.`;

const parsed = metalsmith.matter.parse(fileContent);

console.log('Metadata:', {
  title: parsed.title,      // "My Article"
  date: parsed.date,        // Date object
  tags: parsed.tags,        // ["javascript", "metalsmith"]
  excerpt: parsed.excerpt   // "This is a preview" (if excerpt enabled)
});

console.log('Content:', parsed.contents.toString());
// "# Article Content\n\nThis is the main content..."

/**
 * Stringify file object to front-matter format
 * @param file - File object with contents and metadata
 * @returns String with front-matter header and content
 */
matter.stringify(file: File): string;

const fileObj = {
  contents: Buffer.from('# Hello World\n\nContent here.'),
  title: 'Hello World',
  date: new Date('2024-01-01'),
  published: true
};

const stringified = metalsmith.matter.stringify(fileObj);
console.log(stringified);

// Output:
// ---
// title: Hello World
// date: 2024-01-01T00:00:00.000Z
// published: true
// ---
// # Hello World
// 
// Content here.

/**
 * Get current parser options
 * @returns Current gray-matter options
 */
matter.options(): GrayMatterOptions;

/**
 * Set parser options
 * @param options - Gray-matter configuration options
 */
matter.options(options: GrayMatterOptions): void;

// Get current options
const currentOptions = metalsmith.matter.options();
console.log('Current language:', currentOptions.language);

// Set new options
metalsmith.matter.options({
  excerpt: true,
  excerpt_separator: '<!-- more -->',
  language: 'yaml'
});

// Enable custom engine for TOML
metalsmith.matter.options({
  engines: {
    toml: {
      parse: (str) => require('toml').parse(str),
      stringify: (data) => require('toml').stringify(data)
    }
  }
});

/**
 * Wrap data string with front-matter delimiters
 * @param data - Stringified front-matter data
 * @returns Data wrapped with configured delimiters
 */
matter.wrap(data: string): string;

const metadata = 'title: My Page\ndate: 2024-01-01';
const wrapped = metalsmith.matter.wrap(metadata);
console.log(wrapped);

// Output:
// ---
// title: My Page
// date: 2024-01-01
// ---

// File: src/blog/post.md
// ---
// title: My Blog Post
// date: 2024-01-01
// tags: [web, javascript]
// draft: false
// ---
// # Post Content
// 
// This is my blog post content.

// After reading with metalsmith.read()
const files = await metalsmith.read();
const post = files['blog/post.md'];

console.log(post.title);    // "My Blog Post"
console.log(post.date);     // Date object
console.log(post.tags);     // ["web", "javascript"]
console.log(post.draft);    // false
console.log(post.contents.toString()); // "# Post Content\n\nThis is..."

// Enable excerpt processing
metalsmith.frontmatter({
  excerpt: true,
  excerpt_separator: '<!-- excerpt -->'
});

// File with excerpt:
// ---
// title: Article
// ---
// This is the excerpt content.
// <!-- excerpt -->
// This is the full article content...

const files = await metalsmith.read();
const article = files['article.md'];

console.log(article.excerpt); // "This is the excerpt content."
console.log(article.contents.toString()); // "This is the full article content..."

// YAML (default)
metalsmith.frontmatter({
  language: 'yaml',
  delimiters: '---'
});

// JSON front-matter
metalsmith.frontmatter({
  language: 'json',
  delimiters: [';;;', ';;;']
});

// File with JSON front-matter:
// ;;;
// {
//   "title": "My Article",
//   "published": true
// }
// ;;;
// Content here...

// TOML front-matter
metalsmith.frontmatter({
  language: 'toml',
  delimiters: '+++',
  engines: {
    toml: require('toml')
  }
});

// File with TOML front-matter:
// +++
// title = "My Article"
// published = true
// +++
// Content here...

try {
  const files = await metalsmith.read();
} catch (error) {
  if (error.code === 'invalid_frontmatter') {
    console.error('Invalid front-matter syntax:', error.message);
    // Error includes file path information
  }
}

// Manual parsing error handling
try {
  const parsed = metalsmith.matter.parse(invalidContent);
} catch (error) {
  console.error('Front-matter parse error:', error.message);
}