Crate frontmatter_gen

Expand description

§Frontmatter Gen (frontmatter-gen)

FrontMatter Gen logo

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

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

§Overview 🚀

frontmatter-gen is a comprehensive Rust library that provides robust 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.

§Key Features 🎯

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

§Available Features 🛠️

This crate provides several feature flags to customise its functionality:

default: Core frontmatter parsing functionality only
cli: Command-line interface tools for quick operations
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.4", features = ["cli"] }

# Enable all features (validation, extraction and static site generation)
frontmatter-gen = { version = "0.0.4", 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.4", 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)?;

    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()));

    let json = to_format(&frontmatter, Format::Json)?;
    println!("JSON output: {}", json);
    assert!(json.contains(r#""title":"My Document""#));

    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

§Static Site Generation 🌐

Build and serve your static site:

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

or from the source code:

# Generate a static site using cargo
cargo run --features="ssg" -- build \
    --content-dir content \
    --output-dir public \
    --template-dir templates

§Serve locally (using Python for demonstration)

# Change to the output directory
cd public

# Serve the site
python -m http.server 8000 --bind 127.0.0.1

Then visit http://127.0.0.1:8000 in your favourite browser.

§Error Handling 🚨

The library provides comprehensive error handling:

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)
            ));
        }
    }
    
    Ok(())
}

§Logging Support 📝

When the logging feature is enabled, the library integrates with Rust’s log crate for detailed debug output. You can use any compatible logger implementation (e.g., env_logger, simple_logger).

§Basic Logging Setup

use frontmatter_gen::extract;
use log::{debug, info, Level, Metadata, Record, set_logger, set_max_level};

struct SimpleLogger;

impl log::Log for SimpleLogger {
    fn enabled(&self, metadata: &Metadata) -> bool {
        metadata.level() <= Level::Debug
    }

    fn log(&self, record: &Record) {
        if self.enabled(record.metadata()) {
            println!(
                "{} [{}] - {}",
                record.target(),
                record.level(),
                record.args()
            );
        }
    }

    fn flush(&self) {}
}

static LOGGER: SimpleLogger = SimpleLogger;

fn init_logger() {
    // Explicitly handle logger initialization error
    if let Err(e) = set_logger(&LOGGER).map(|()| set_max_level(Level::Debug.to_level_filter())) {
        eprintln!("Failed to initialize logger: {}", e);
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize the custom logger
    init_logger();
    info!("Starting frontmatter extraction");

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

    // Extract frontmatter and remaining content
    let (frontmatter, content) = extract(content)?;
    debug!("Extracted frontmatter: {:?}", frontmatter);
    debug!("Remaining content: {:?}", content);

    Ok(())
}

§Advanced Logging Configuration

For more control over logging:

use frontmatter_gen::{parser, Format};
use log::{debug, info, Level, Metadata, Record, set_logger, set_max_level};

struct SimpleLogger;

impl log::Log for SimpleLogger {
    fn enabled(&self, metadata: &Metadata) -> bool {
        metadata.level() <= Level::Debug
    }

    fn log(&self, record: &Record) {
        if self.enabled(record.metadata()) {
            println!("[{}] - {}", record.level(), record.args());
        }
    }

    fn flush(&self) {}
}

static LOGGER: SimpleLogger = SimpleLogger;

fn init_logger() {
    set_logger(&LOGGER).expect("Failed to set logger");
    set_max_level(Level::Debug.to_level_filter());
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize the custom logger
    init_logger();
    info!("Starting frontmatter processing");

    let yaml = r#"title: Test Document"#;
    let frontmatter = parser::parse(yaml, Format::Yaml)?;
    debug!("Parsed frontmatter: {:?}", frontmatter);

    Ok(())
}

§CLI Logging 📝

When using the CLI with logging enabled:

# Set log level via environment variable
RUST_LOG=debug frontmatter_gen extract input.md --format yaml

# Or for more specific control
RUST_LOG=frontmatter_gen=debug,cli=info frontmatter_gen validate input.md

The library provides detailed error handling with context:

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

fn process_content(content: &str) -> Result<(), Error> {
    // Extract frontmatter and content
    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(())
}

§Documentation 📚

For comprehensive API documentation and examples, visit:

§Contributing 🤝

We welcome contributions! Please see our Contributing Guidelines for details on:

Code of Conduct
Development Process
Submitting Pull Requests
Reporting Issues

§Licence 📝

This project is dual-licensed under either:

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT licence (LICENSE-MIT or 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.

Type Aliases§

Result
A specialized Result type for frontmatter operations.

Crate frontmatter_genCopy item path