Frontmatter Processing

/**
 * Parse frontmatter (YAML or TOML) from markdown content
 * @param code - The markdown content containing frontmatter
 * @param options - Optional configuration for frontmatter handling
 * @returns Parsed frontmatter data, raw frontmatter, and processed content
 */
function parseFrontmatter(
  code: string,
  options?: ParseFrontmatterOptions
): ParseFrontmatterResult;

interface ParseFrontmatterOptions {
  /**
   * How the frontmatter should be handled in the returned content string
   * - 'preserve': Keep the frontmatter
   * - 'remove': Remove the frontmatter
   * - 'empty-with-spaces': Replace with spaces (preserves sourcemap line/col/offset)
   * - 'empty-with-lines': Replace with line breaks (preserves sourcemap line/col)
   */
  frontmatter: 'preserve' | 'remove' | 'empty-with-spaces' | 'empty-with-lines';
}

interface ParseFrontmatterResult {
  /** Parsed frontmatter object */
  frontmatter: Record<string, any>;
  /** Raw frontmatter string (without delimiters) */
  rawFrontmatter: string;
  /** Content with frontmatter handled according to options */
  content: string;
}

import { parseFrontmatter } from "@astrojs/markdown-remark";

const markdown = `---
title: "My Blog Post"
tags: ["javascript", "tutorial"]
published: true
date: 2023-12-01
---

# Hello World

This is the content of my blog post.`;

// Default behavior (remove frontmatter)
const result = parseFrontmatter(markdown);
console.log(result.frontmatter); // { title: "My Blog Post", tags: [...], published: true, date: 2023-12-01 }
console.log(result.content); // "# Hello World\n\nThis is the content..."

// Preserve frontmatter in content
const preserved = parseFrontmatter(markdown, { frontmatter: 'preserve' });
console.log(preserved.content); // Original markdown with frontmatter intact

// Replace with spaces (useful for sourcemaps)
const withSpaces = parseFrontmatter(markdown, { frontmatter: 'empty-with-spaces' });
console.log(withSpaces.content); // Frontmatter area replaced with spaces

// TOML frontmatter support
const tomlMarkdown = `+++
title = "TOML Example"
tags = ["toml", "config"]
+++

# TOML Content`;

const tomlResult = parseFrontmatter(tomlMarkdown);
console.log(tomlResult.frontmatter); // { title: "TOML Example", tags: [...] }

/**
 * Extract raw frontmatter content from markdown
 * @param code - The markdown content
 * @returns Raw frontmatter string without delimiters, or undefined if no frontmatter
 */
function extractFrontmatter(code: string): string | undefined;

import { extractFrontmatter } from "@astrojs/markdown-remark";

const markdown = `---
title: "Example"
date: 2023-12-01
---

# Content`;

const raw = extractFrontmatter(markdown);
console.log(raw); // "title: \"Example\"\ndate: 2023-12-01\n"

// No frontmatter case
const noFrontmatter = extractFrontmatter("# Just a heading");
console.log(noFrontmatter); // undefined

/**
 * Validate if frontmatter object is JSON-serializable
 * @param frontmatter - The frontmatter object to validate
 * @returns true if valid, false if not serializable
 */
function isFrontmatterValid(frontmatter: Record<string, any>): boolean;

import { isFrontmatterValid } from "@astrojs/markdown-remark";

// Valid frontmatter
const validFrontmatter = {
  title: "My Post",
  tags: ["tag1", "tag2"],
  published: true,
  date: new Date().toISOString()
};
console.log(isFrontmatterValid(validFrontmatter)); // true

// Invalid frontmatter (circular reference)
const invalidFrontmatter: any = { title: "Test" };
invalidFrontmatter.self = invalidFrontmatter;
console.log(isFrontmatterValid(invalidFrontmatter)); // false

// Invalid frontmatter (function)
const withFunction = {
  title: "Test",
  callback: () => console.log("hello")
};
console.log(isFrontmatterValid(withFunction)); // false

---
title: "YAML Example"
tags:
  - yaml
  - frontmatter
metadata:
  author: "John Doe"
  published: true
  date: 2023-12-01T10:00:00Z
---

+++
title = "TOML Example"
tags = ["toml", "frontmatter"]

[metadata]
author = "John Doe"
published = true
date = 2023-12-01T10:00:00Z
+++

const result = parseFrontmatter(markdown, { frontmatter: 'preserve' });
// result.content includes the original frontmatter delimiters and content

const result = parseFrontmatter(markdown); // default behavior
// result.content starts with the first line after frontmatter

const result = parseFrontmatter(markdown, { frontmatter: 'empty-with-spaces' });
// Useful for source maps and error reporting with accurate line/column numbers

const result = parseFrontmatter(markdown, { frontmatter: 'empty-with-lines' });
// Preserves line numbers but not column positions