Crate frontmatter_gen

Frontmatter Gen (frontmatter-gen)

A high-performance Rust library for parsing and serialising frontmatter in YAML, TOML, and JSON formats. Engineered for safety, efficiency, and ease of use.

• Website • Documentation • Report Bug • Request Feature • Contributing Guidelines

Overview 🚀

frontmatter-gen is a robust Rust library that provides comprehensive handling of frontmatter in content files. It delivers a type-safe, efficient solution for extracting, parsing, and serialising frontmatter in multiple formats. Whether you’re building a static site generator, content management system, or any application requiring structured metadata, frontmatter-gen offers the tools you need with performance and safety at its core.

Key Features 🎯

• Zero-copy parsing: Optimised for memory efficiency
• Multi-format support: Parse and serialise YAML, TOML, and JSON
• Type-safe operations: Comprehensive error handling with Result types
• Secure processing: Input validation and size limits
• Async support: Full asynchronous operations via the ssg feature flag
• Command-line interface: Direct frontmatter manipulation tools
• Memory safety: Guaranteed memory safety through Rust’s ownership system
• Comprehensive testing: Extensive test coverage and validation
• Rich documentation: Detailed guides and examples

Available Features 🛠️

This crate provides several feature flags to customise its functionality:

• default: Core frontmatter parsing functionality
• cli: Command-line interface tools for validation and extraction
• ssg: Static Site Generator functionality (includes CLI features)

Configure features in your Cargo.toml:

[dependencies]
# Enable CLI support for validation and extraction
frontmatter-gen = { version = "0.0.5", features = ["cli"] }

# Enable all features (validation, extraction and static site generation)
frontmatter-gen = { version = "0.0.5", features = ["ssg"] }

Installation via Cargo:

# Install with CLI support
cargo install frontmatter-gen --features="cli"

# Install with SSG support
cargo install frontmatter-gen --features="ssg"

Getting Started 📦

Library Usage

Add this to your Cargo.toml:

[dependencies]
# Core library with command-line interface and SSG support
frontmatter-gen = { version = "0.0.5", features = ["cli", "ssg"] }

Basic Usage 🔨

Extract and Parse Frontmatter

use frontmatter_gen::extract;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let content = r#"---
title: My Document
date: 2025-09-09
tags:
  - documentation
  - rust
---

    let (frontmatter, content) = extract(content)?;

    // Access frontmatter fields safely
    if let Some(title) = frontmatter.get("title").and_then(|v| v.as_str()) {
        println!("Title: {}", title);
    }

    println!("Content: {}", content);
    Ok(())
}

Format Conversion

use frontmatter_gen::{Frontmatter, Format, Value, to_format};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut frontmatter = Frontmatter::new();
    frontmatter.insert(
        "title".to_string(), 
        Value::String("My Document".to_string())
    );

    // Convert to different formats
    let yaml = to_format(&frontmatter, Format::Yaml)?;
    let json = to_format(&frontmatter, Format::Json)?;
    let toml = to_format(&frontmatter, Format::Toml)?;

    println!("YAML output:\n{}", yaml);
    println!("JSON output:\n{}", json);
    println!("TOML output:\n{}", toml);

    Ok(())
}

CLI Tool 🛠️

The fmg command provides comprehensive frontmatter operations:

# Extract frontmatter in various formats
fmg extract input.md --format yaml
fmg extract input.md --format toml
fmg extract input.md --format json

# Save extracted frontmatter
fmg extract input.md --format yaml --output frontmatter.yaml

# Validate frontmatter
fmg validate input.md --required title,date,author

You can also use the CLI directly from the source code:

# Extract frontmatter in various formats
cargo run --features="cli" extract input.md --format yaml
cargo run --features="cli" extract input.md --format toml
cargo run --features="cli" extract input.md --format json

# Save extracted frontmatter
cargo run --features="cli" extract input.md --format yaml --output frontmatter.yaml

# Validate frontmatter
cargo run --features="cli" validate input.md --required title,date,author

Static Site Generation 🌐

Build and serve your static site:

# Generate a static site
fmg build \
    --content-dir content \
    --output-dir public \
    --template-dir templates

# Or using cargo
cargo run --features="ssg" -- build \
    --content-dir content \
    --output-dir public \
    --template-dir templates

Local Development Server

# Change to the output directory
cd public

# Start a local server (using Python for demonstration)
python -m http.server 8000 --bind 127.0.0.1

Visit http://127.0.0.1:8000 in your browser to view the site.

Error Handling 🚨

The library provides comprehensive error handling with context:

use frontmatter_gen::{extract, error::Error};

fn process_content(content: &str) -> Result<(), Error> {
    let (frontmatter, _) = extract(content)?;
    
    // Validate required fields
    for field in ["title", "date", "author"].iter() {
        if !frontmatter.contains_key(*field) {
            return Err(Error::ValidationError(
                format!("Missing required field: {}", field)
            ));
        }
    }
    
    // Validate field types
    if let Some(date) = frontmatter.get("date") {
        if !date.is_string() {
            return Err(Error::ValidationError(
                "Date field must be a string".to_string()
            ));
        }
    }
    
    Ok(())
}

Logging Support 📝

Enable detailed logging with the standard Rust logging facade:

use frontmatter_gen::extract;
use log::{debug, info, Level};
use simple_logger::SimpleLogger;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialise logging
    SimpleLogger::new()
        .with_level(Level::Debug.to_level_filter())
        .init()?;

    let content = r#"---
title: My Document
date: 2025-09-09
---

    info!("Processing frontmatter");
    let (frontmatter, content) = extract(content)?;
    debug!("Extracted frontmatter: {:?}", frontmatter);
    debug!("Content: {:?}", content);

    Ok(())
}

CLI Logging Configuration

Control logging levels via environment variables:

# Set log level for CLI operations
RUST_LOG=debug fmg extract input.md --format yaml

# Configure specific component logging
RUST_LOG=frontmatter_gen=debug,cli=info fmg validate input.md

Documentation 📚

Comprehensive documentation is available at:

• API Documentation
• User Guide and Examples
• Source Code and Examples

Contributing 🤝

We welcome contributions! Please see our Contributing Guidelines for:

• Code of Conduct
• Development Process
• Pull Request Guidelines
• Issue Reporting

Licence 📝

This project is dual-licensed under either:

• Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0)
• MIT Licence (http://opensource.org/licenses/MIT)

at your option.

Acknowledgements 🙏

Special thanks to all contributors and the Rust community for their invaluable support and feedback.

Frontmatter Gen

frontmatter-gen is a fast, secure, and memory-efficient library for working with frontmatter in multiple formats (YAML, TOML, and JSON).

Overview

This library provides robust handling of frontmatter with the following key features:

• Zero-copy parsing for optimal memory efficiency
• Type-safe operations with comprehensive error handling
• Multiple format support (YAML, TOML, JSON)
• Secure processing with input validation and size limits
• Async support with the ssg feature flag

Security Features

• Input validation to prevent malicious content
• Size limits to prevent denial of service attacks
• Safe string handling to prevent memory corruption
• Secure path handling for file operations

Quick Start

use frontmatter_gen::{extract, Format, Frontmatter, Result};

let content = r#"---
title: Test Post
date: 2025-09-09
---
Content here"#;

let result = extract(content);
assert!(result.is_ok());
let (frontmatter, content) = result.unwrap();
assert_eq!(
    frontmatter.get("title").and_then(|v| v.as_str()),
    Some("Test Post")
);
assert_eq!(content.trim(), "Content here");

Feature Flags

• default: Core frontmatter functionality
• cli: Command-line interface support
• ssg: Static Site Generator functionality (includes CLI)

Error Handling

All operations return a Result type with detailed error information:

use frontmatter_gen::{extract, Error};

fn process_content(content: &str) -> Result<(), Error> {
    let (frontmatter, _) = extract(content)?;

    // Validate required fields
    if !frontmatter.contains_key("title") {
        return Err(Error::ValidationError(
            "Missing required field: title".to_string()
        ));
    }

    Ok(())
}

Re-exports

• pub use crate::config::Config;
• pub use crate::error::Error;
• pub use crate::extractor::detect_format;
• pub use crate::extractor::extract_raw_frontmatter;
• pub use crate::parser::parse;
• pub use crate::parser::to_string;
• pub use crate::types::Format;
• pub use crate::types::Frontmatter;
• pub use crate::types::Value;

Modules

• cli
  Command Line Interface Module
• config
  Configuration Module
• engine
  Site Generation Engine
• error
  Error handling for the frontmatter-gen crate.
• extractor
  This module provides functionality for extracting frontmatter from content.
• parser
  Front Matter Parser and Serialiser Module
• prelude
  Prelude module for convenient imports.
• ssg
  Static Site Generator Module
• types
  This module defines the core types used throughout the frontmatter-gen crate. It includes the Format enum for representing different frontmatter formats, the Value enum for representing various data types that can be stored in frontmatter, and the Frontmatter struct which is the main container for frontmatter data.
• utils
  Utility Module

Structs

• ParseOptions
  Configuration options for parsing operations.

Constants

• MAX_FRONTMATTER_SIZE
  Maximum size allowed for frontmatter content (1MB)
• MAX_NESTING_DEPTH
  Maximum allowed nesting depth for structured data

Functions

• extract
  Extracts and parses frontmatter from content with format auto-detection.
• to_format
  Converts frontmatter to a specific format.
• validate_input
  Validates input content against security constraints.

Type Aliases

• Result
  A specialized Result type for frontmatter operations.