Merge pull request #1509 from rust-lang/senekor/normalize-front-matter

Normalize front matter

Author: Manishearth

Cargo.lock

@@ -1,26 +1,46 @@
-[package]
-name = "blog"
-version = "0.1.0"
-authors = ["The Rust Project Developers"]
-edition = "2021"
+[workspace]
+members = ["front_matter", "serve"]
 
-[dependencies]
+[workspace.package]
+edition = "2024"
+
+[workspace.dependencies]
+blog = { path = "." }
+chrono = "=0.4.40"
 color-eyre = "=0.6.3"
+comrak = "=0.36.0"
 eyre = "=0.6.12"
-lazy_static = "=1.5.0"
-serde = "=1.0.218"
-serde_derive = "=1.0.218"
-serde_json = "=1.0.140"
-comrak = { version = "=0.36.0", features = ["bon"] }
+front_matter = { path = "front_matter" }
+insta = "=1.42.2"
 rayon = "=1.10.0"
 regex = "=1.11.1"
 sass-rs = "=0.2.2"
-chrono = "=0.4.40"
+serde_json = "=1.0.140"
+serde = "=1.0.218"
 tera = "=1.20.0"
+tokio = "=1.44.0"
 toml = "=0.8.20"
+warpy = "=0.3.68"
 
-[workspace]
-members = ["serve"]
+[package]
+name = "blog"
+version = "0.1.0"
+edition.workspace = true
+authors = ["The Rust Project Developers"]
+
+[dependencies]
+chrono.workspace = true
+color-eyre.workspace = true
+comrak = { workspace = true, features = ["bon"] }
+eyre.workspace = true
+front_matter.workspace = true
+rayon.workspace = true
+regex.workspace = true
+sass-rs.workspace = true
+serde_json.workspace = true
+serde = { workspace = true, features = ["derive"] }
+tera.workspace = true
+toml.workspace = true
 
 [dev-dependencies]
-insta = { version = "=1.42.2", features = ["filters", "glob"] }
+insta = { workspace = true, features = ["filters", "glob"] }

Cargo.toml

@@ -0,0 +1,9 @@
+[package]
+name = "front_matter"
+version = "0.1.0"
+edition.workspace = true
+
+[dependencies]
+eyre.workspace = true
+serde = { workspace = true, features = ["derive"] }
+toml.workspace = true

front_matter/Cargo.toml

@@ -0,0 +1,105 @@
+use eyre::bail;
+use serde::{Deserialize, Serialize};
+
+/// The front matter of a markdown blog post.
+#[derive(Debug, PartialEq, Serialize, Deserialize)]
+pub struct FrontMatter {
+    pub layout: String,
+    pub title: String,
+    pub author: String,
+    pub description: Option<String>,
+    pub team: Option<String>,
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub release: bool,
+}
+
+/// Extracts the front matter from a markdown file.
+///
+/// The remaining normal markdown content is returned as the second element of
+/// the tuple.
+pub fn parse(markdown: &str) -> eyre::Result<(FrontMatter, &str)> {
+    if !markdown.starts_with("+++\n") {
+        bail!("markdown file must start with the line `+++`");
+    }
+    let (front_matter, content) = markdown
+        .trim_start_matches("+++\n")
+        .split_once("\n+++\n")
+        .expect("couldn't find the end of the front matter: `+++`");
+
+    Ok((toml::from_str(front_matter)?, content))
+}
+
+/// Normalizes the front matter of a markdown file.
+pub fn normalize(markdown: &str) -> eyre::Result<String> {
+    let (front_matter, content) = parse(markdown)?;
+
+    Ok(format!(
+        "\
++++
+{}\
++++
+{content}",
+        toml::to_string_pretty(&front_matter)?
+    ))
+}
+
+#[cfg(test)]
+mod tests {
+    use std::{env, fs, path::PathBuf};
+
+    use super::*;
+
+    #[test]
+    fn front_matter_is_normalized() {
+        let repo_root = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("..");
+
+        let posts = fs::read_dir(repo_root.join("posts"))
+            .unwrap()
+            .chain(fs::read_dir(repo_root.join("posts/inside-rust")).unwrap())
+            .map(|p| p.unwrap().path())
+            .filter(|p| p.extension() == Some("md".as_ref()));
+
+        for post in posts {
+            let content = fs::read_to_string(&post).unwrap();
+            let normalized = normalize(&content).unwrap();
+
+            if content != normalized {
+                if env::var("FIX_FRONT_MATTER").is_ok() {
+                    fs::write(post, normalized).unwrap();
+                    continue;
+                }
+
+                let post = post.file_name().unwrap().to_str().unwrap();
+                let actual = content
+                    .rsplit_once("+++")
+                    .map(|(f, _)| format!("{f}+++"))
+                    .unwrap_or(content);
+                let expected = normalized
+                    .rsplit_once("+++")
+                    .map(|(f, _)| format!("{f}+++"))
+                    .unwrap_or(normalized);
+
+                // better error message than assert_eq!()
+                panic!(
+                    "
+The post {post} has abnormal front matter.
+
+    actual:
+{actual}
+
+    expected:
+{expected}
+
+    ┌──────────────────────────────────────────────────────────────────────────┐
+    │                                                                          │
+    │                You can fix this automatically by running:                │
+    │                                                                          │
+    │      FIX_FRONT_MATTER=1 cargo test --all front_matter_is_normalized      │
+    │                                                                          │
+    └──────────────────────────────────────────────────────────────────────────┘
+",
+                )
+            };
+        }
+    }
+}

front_matter/src/lib.rs

@@ -1,7 +1,7 @@
 +++
+layout = "post"
 title = "New Year's Rust: A Call for Community Blogposts"
 author = "The Rust Core Team"
-layout = "post"
 +++
 
 'Tis the season for people and communities to reflect and set goals- and the Rust team is

posts/2018-01-03-new-years-rust-a-call-for-community-blogposts.md

@@ -1,7 +1,7 @@
 +++
+layout = "post"
 title = "Help test Rust 2018"
 author = "The Rust Core Team"
-layout = "post"
 +++
 
 Back in July, we talked about ["Rust 2018"]. In short, we are launching a

posts/2018-10-30-help-test-rust-2018.md

@@ -2,7 +2,6 @@
 layout = "post"
 title = "The Governance WG is going public"
 author = "The Rust Governance WG"
-release = false
 +++
 
 

posts/2019-06-03-governance-wg-announcement.md

@@ -2,7 +2,6 @@
 layout = "post"
 title = "Laying the foundation for Rust's future"
 author = "The Rust Core Team"
-release = false
 +++
 
 The Rust project was originally [conceived in 2010][2010] (depending on how you count, you might even say [2006][2006]!) as a [Mozilla Research] project, but the long term goal has always been to establish Rust as a self-sustaining project. In 2015, [with the launch of Rust 1.0][onepointoh], Rust established its project direction and governance independent of the Mozilla organization. Since then, Rust has been operating as an autonomous organization, with Mozilla being a prominent and consistent financial and legal sponsor.

posts/2020-08-18-laying-the-foundation-for-rusts-future.md

@@ -2,7 +2,6 @@
 layout = "post"
 title = "Planning the 2021 Roadmap"
 author = "The Rust Core Team"
-release = false
 +++
 
 The core team is beginning to think about the 2021 Roadmap, and we want to hear from the community. We’re going to be running two parallel efforts over the next several weeks: the 2020 Rust Survey, to be announced next week, and a call for blog posts.

posts/2020-09-03-Planning-2021-Roadmap.md

@@ -2,7 +2,6 @@
 layout = "post"
 title = "Call for 2021 Roadmap Blogs Ending Soon"
 author = "The Rust Core Team"
-release = false
 +++
 
 We will be closing the collection of blog posts on **October 5th**. As a reminder, we plan to close the [survey](https://blog.rust-lang.org/2020/09/10/survey-launch.html) on **September 24th**, later this week.