Adding Frontmatter Reader: Support summary card (OG. Twitter)

Cargo.toml

@@ -128,6 +128,7 @@ default = ["watch", "serve", "search"]
 watch = ["dep:notify", "dep:notify-debouncer-mini", "dep:ignore", "dep:pathdiff", "dep:walkdir"]
 serve = ["dep:futures-util", "dep:tokio", "dep:axum", "dep:tower-http"]
 search = ["mdbook-html/search"]
+frontmatter = ["mdbook-html/frontmatter"]
 
 [[bin]]
 doc = false

crates/mdbook-html/Cargo.toml

@@ -23,6 +23,7 @@ pulldown-cmark.workspace = true
 regex.workspace = true
 serde.workspace = true
 serde_json.workspace = true
+serde_yml = { version = "0.0.12", optional = true }
 sha2.workspace = true
 tracing.workspace = true
 
@@ -35,3 +36,4 @@ workspace = true
 
 [features]
 search = ["dep:elasticlunr-rs"]
+frontmatter = ["dep:serde_yml"]

crates/mdbook-html/front-end/templates/index.hbs

@@ -15,10 +15,34 @@
         <!-- Custom HTML head -->
         {{> head}}
 
-        <meta name="description" content="{{ description }}">
         <meta name="viewport" content="width=device-width, initial-scale=1">
         <meta name="theme-color" content="#ffffff">
 
+        <!-- Open Graph Meta Tags for Social Media Exposure -->
+        {{#if is_frontmatter}}
+        <meta name="title" property="og:title" content="{{ og_title }}">
+        <meta name="description" property="og:description" content="{{ og_description }}">
+        <meta name="twitter:title" content="{{ og_title }}"/>
+        <meta name="twitter:description" content="{{ og_description }}"/>
+        {{else}}
+        <meta name="title" property="og:title" content="{{ book_title }}">
+        <meta name="description" property="og:description" content="{{ description }}">
+        <meta name="twitter:title" content="{{ book_title }}"/>
+        <meta name="twitter:description" content="{{ description }}"/>
+        {{/if}}
+        {{#if og_image_url}}
+        <meta property="og:image" content="{{ og_image_url }}">
+        <meta name="twitter:image" content="{{ og_image_url }}"/>
+        {{else}}
+        <meta property="og:image" content="https://avatars.githubusercontent.com/u/5430905?s=48&v=4">
+        <meta name="twitter:image" content="https://avatars.githubusercontent.com/u/5430905?s=48&v=4"/>
+        {{/if}}
+
+        <meta name="author" content="mdBook">
+        <meta property="og:type" content="book">
+        <meta name="twitter:card" content="summary_large_image"/>
+        <meta name="twitter:creator" content="@rust_foundation"/>
+
         {{#if favicon_svg}}
         <link rel="icon" href="{{ resource "favicon.svg" }}">
         {{/if}}

crates/mdbook-html/src/frontmatter.rs

@@ -0,0 +1,101 @@
+//! Frontmatter parsing support for mdBook.
+//!
+//! Extracts YAML frontmatter from markdown content and injects
+//! Open Graph / Twitter Card metadata into the Handlebars template context.
+
+use serde::Deserialize;
+use serde_json::json;
+
+/// Parsed YAML frontmatter fields.
+#[derive(Deserialize, Debug)]
+pub(crate) struct FrontMatter {
+    /// Page title for OG/Twitter meta tags.
+    pub title: String,
+    /// Page description for OG/Twitter meta tags.
+    pub description: String,
+    /// Featured image URL for OG/Twitter meta tags.
+    pub featured_image_url: String,
+}
+
+/// Strips YAML frontmatter (between `---` markers) from content,
+/// returning the content without the frontmatter block.
+pub(crate) fn strip_frontmatter(content: &str) -> String {
+    let trimmed = content.trim_start();
+    if !trimmed.starts_with("---") {
+        return content.to_string();
+    }
+    // Find the closing `---` after the opening one
+    let after_open = &trimmed[3..];
+    if let Some(end) = after_open.find("\n---") {
+        // Skip past the closing `---` and any trailing newline
+        let rest = &after_open[end + 4..];
+        rest.trim_start_matches('\n').to_string()
+    } else {
+        content.to_string()
+    }
+}
+
+/// Parses YAML frontmatter from content and injects OG metadata
+/// into the Handlebars template context data map.
+pub(crate) fn inject_frontmatter_data(
+    content: &str,
+    data: &mut serde_json::Map<String, serde_json::Value>,
+) {
+    let trimmed = content.trim_start();
+    if !trimmed.starts_with("---") {
+        return;
+    }
+    let after_open = &trimmed[3..];
+    let Some(end) = after_open.find("\n---") else {
+        return;
+    };
+    let yaml_str = &after_open[..end];
+
+    match serde_yml::from_str::<FrontMatter>(yaml_str) {
+        Ok(fm) => {
+            data.insert("is_frontmatter".to_owned(), json!(true));
+            data.insert("og_title".to_owned(), json!(fm.title));
+            data.insert("og_description".to_owned(), json!(fm.description));
+            data.insert("og_image_url".to_owned(), json!(fm.featured_image_url));
+        }
+        Err(e) => {
+            eprintln!("Frontmatter: deserialization error: {e:?}");
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_strip_frontmatter() {
+        let input = "---\ntitle: \"Hello\"\n---\n# Content";
+        assert_eq!(strip_frontmatter(input), "# Content");
+    }
+
+    #[test]
+    fn test_strip_no_frontmatter() {
+        let input = "# Just content";
+        assert_eq!(strip_frontmatter(input), "# Just content");
+    }
+
+    #[test]
+    fn test_inject_frontmatter_data() {
+        let input = "---\ntitle: \"My Title\"\ndescription: \"My Desc\"\nfeatured_image_url: \"https://example.com/img.png\"\n---\n# Content";
+        let mut data = serde_json::Map::new();
+        inject_frontmatter_data(input, &mut data);
+        assert_eq!(data["is_frontmatter"], json!(true));
+        assert_eq!(data["og_title"], json!("My Title"));
+        assert_eq!(data["og_description"], json!("My Desc"));
+        assert_eq!(data["og_image_url"], json!("https://example.com/img.png"));
+    }
+
+    #[test]
+    fn test_inject_no_frontmatter() {
+        let input = "# Just content";
+        let mut data = serde_json::Map::new();
+        inject_frontmatter_data(input, &mut data);
+        assert!(!data.contains_key("is_frontmatter"));
+    }
+}

crates/mdbook-html/src/html/mod.rs

@@ -96,7 +96,11 @@ pub(crate) fn build_trees<'book>(
             let path = ch.path.as_ref().unwrap();
             let html_path = ch.path.as_ref().unwrap().with_extension("html");
             let options = HtmlRenderOptions::new(path, html_config, edition);
-            let tree = build_tree(&ch.content, &options);
+            #[cfg(feature = "frontmatter")]
+            let chapter_content = crate::frontmatter::strip_frontmatter(&ch.content);
+            #[cfg(not(feature = "frontmatter"))]
+            let chapter_content = ch.content.clone();
+            let tree = build_tree(&chapter_content, &options);
 
             ChapterTree {
                 chapter: ch,

crates/mdbook-html/src/html_handlebars/hbs_renderer.rs

@@ -115,6 +115,10 @@ impl HtmlHandlebars {
         nav("previous", prev_ch);
         nav("next", next_ch);
 
+        // Inject frontmatter OG metadata into template context
+        #[cfg(feature = "frontmatter")]
+        crate::frontmatter::inject_frontmatter_data(&ch.content, &mut ctx.data);
+
         // Render the handlebars template with the data
         debug!("Render template");
         let rendered = ctx.handlebars.render("index", &ctx.data)?;

crates/mdbook-html/src/lib.rs

@@ -5,4 +5,7 @@ mod html_handlebars;
 pub mod theme;
 pub(crate) mod utils;
 
+#[cfg(feature = "frontmatter")]
+pub(crate) mod frontmatter;
+
 pub use html_handlebars::HtmlHandlebars;

tests/testsuite/config.rs

@@ -279,7 +279,7 @@ fn env_entire_book_table() {
         .check_file_contains("book/index.html", "<title>Chapter 1</title>")
         .check_file_contains(
             "book/index.html",
-            r#"<meta name="description" content="custom description">"#,
+            r#"<meta name="description" property="og:description" content="custom description">"#,
         );
 }