Crate gray_matter[][src]

Expand description

gray_matter is a tool for easily extracting front matter out of a string. It is a fast Rust implementation of the original gray-matter by Jon Schlinkert.

What can gray_matter do?

It can take some string or file like this:

title: This is the title
    - awesome-tag
    - more-awesome-tag

This is my really cool document!

and strip the YAML contained within the delimiters (---), to create a struct like this1:

MyStruct {
    title: "This is the title",
    tags: ["awesome-tag", "more-awesome-tag"]

Why would I use this?

You want to have configurability inside plain text documents, like for example a Markdown document. Pandoc and Hugo are examples of tools that use this kind of configuration, but the sky really is the limit.

What formats are supported?

gray_matter has built in support for YAML, TOML and JSON, but the Engine trait allows for virtually any format you wish to be supported.


Basic parsing

use gray_matter::Matter;
use gray_matter::engine::YAML;
use serde::Deserialize;

const INPUT: &str = r#"---
title: gray-matter-rs
  - gray-matter
  - rust
Some excerpt
Other stuff

fn main() {
    // Select one parser engine, such as YAML, and parse it
    // into gray_matter's custom data type: `Pod`
    let matter = Matter::<YAML>::new();
    let result = matter.parse(INPUT);

    // You can now inspect the data from gray_matter.
    assert_eq!(result.content, "Some excerpt\n---\nOther stuff");
    assert_eq!(result.excerpt, Some("Some excerpt".to_owned()));
    assert_eq!(["title"].as_string(), Ok("gray-matter-rs".to_string()));
    assert_eq!(["tags"][0].as_string(), Ok("gray-matter".to_string()));
    assert_eq!(["tags"][1].as_string(), Ok("rust".to_string()));

    // The `Pod` data type can be a bit unwieldy, so
    // you can also deserialize it into a custom struct
    #[derive(Deserialize, Debug)]
    struct FrontMatter {
        title: String,
        tags: Vec<String>

    // Deserialize `result` manually:
    let front_matter: FrontMatter =;
    println!("{:?}", front_matter);
    // FrontMatter { title: "gray-matter-rs", tags: ["gray-matter", "rust"] }

    // ...or skip a step, by using `parse_with_struct`.
    let result_with_struct = matter.parse_with_struct::<FrontMatter>(INPUT).unwrap();
    // FrontMatter { title: "gray-matter-rs", tags: ["gray-matter", "rust"] }

  1. The struct is purely for demonstration. 


A module containing the Engine trait, along with gray_matter’s default engines.


Coupled with an Engine of choice, Matter stores delimiter(s) and handles parsing.

ParsedEntity stores a parsed result.

ParsedEntityStruct stores the parsed result with the front matter deserialized into a struct T.


A polyglot data type for representing the parsed front matter.