Merge pull request #2826 from ehuss/guide-version

Add the mdbook version to the guide

Cargo.lock

@@ -767,6 +767,16 @@ dependencies = [
  "regex-syntax",
 ]
 
+[[package]]
+name = "guide-helper"
+version = "0.0.0"
+dependencies = [
+ "mdbook-preprocessor",
+ "semver",
+ "serde_json",
+ "toml",
+]
+
 [[package]]
 name = "handlebars"
 version = "6.3.2"

Cargo.toml

@@ -2,7 +2,7 @@
 members = [
     ".",
     "crates/*",
-    "examples/remove-emphasis/mdbook-remove-emphasis",
+    "examples/remove-emphasis/mdbook-remove-emphasis", "guide/guide-helper",
 ]
 
 [workspace.lints.clippy]

guide/book.toml

@@ -33,3 +33,9 @@ heading-split-level = 2
 
 [output.html.redirect]
 "/format/config.html" = "configuration/index.html"
+
+[preprocessor.guide-helper]
+command = "cargo run --quiet --manifest-path guide-helper/Cargo.toml"
+
+[build]
+extra-watch-dirs = ["guide-helper/src"]

guide/guide-helper/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "guide-helper"
+publish = false
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+mdbook-preprocessor.workspace = true
+semver.workspace = true
+serde_json.workspace = true
+toml.workspace = true
+
+[lints]
+workspace = true

guide/guide-helper/src/lib.rs

@@ -0,0 +1,67 @@
+//! Preprocessor for the mdBook guide.
+
+use mdbook_preprocessor::book::{Book, BookItem};
+use mdbook_preprocessor::errors::Result;
+use mdbook_preprocessor::{Preprocessor, PreprocessorContext};
+use semver::{Version, VersionReq};
+use std::io;
+
+/// Preprocessing entry point.
+pub fn handle_preprocessing() -> Result<()> {
+    let pre = GuideHelper;
+    let (ctx, book) = mdbook_preprocessor::parse_input(io::stdin())?;
+
+    let book_version = Version::parse(&ctx.mdbook_version)?;
+    let version_req = VersionReq::parse(mdbook_preprocessor::MDBOOK_VERSION)?;
+
+    if !version_req.matches(&book_version) {
+        eprintln!(
+            "warning: The {} plugin was built against version {} of mdbook, \
+             but we're being called from version {}",
+            pre.name(),
+            mdbook_preprocessor::MDBOOK_VERSION,
+            ctx.mdbook_version
+        );
+    }
+
+    let processed_book = pre.run(&ctx, book)?;
+    serde_json::to_writer(io::stdout(), &processed_book)?;
+
+    Ok(())
+}
+
+struct GuideHelper;
+
+impl Preprocessor for GuideHelper {
+    fn name(&self) -> &str {
+        "guide-helper"
+    }
+
+    fn run(&self, _ctx: &PreprocessorContext, mut book: Book) -> Result<Book> {
+        insert_version(&mut book);
+        Ok(book)
+    }
+}
+
+fn insert_version(book: &mut Book) {
+    let path = std::env::current_dir()
+        .unwrap()
+        .parent()
+        .unwrap()
+        .join("Cargo.toml");
+    let manifest_contents = std::fs::read_to_string(&path).unwrap();
+    let manifest: toml::Value = toml::from_str(&manifest_contents).unwrap();
+    let version = manifest["package"]["version"].as_str().unwrap();
+    const MARKER: &str = "{{ mdbook-version }}";
+    book.for_each_mut(|item| {
+        let BookItem::Chapter(ch) = item else {
+            return;
+        };
+        if ch.is_draft_chapter() {
+            return;
+        }
+        if ch.content.contains(MARKER) {
+            ch.content = ch.content.replace(MARKER, version);
+        }
+    });
+}

guide/guide-helper/src/main.rs

@@ -0,0 +1,21 @@
+//! Preprocessor for the mdBook guide.
+
+fn main() {
+    let mut args = std::env::args().skip(1);
+    match args.next().as_deref() {
+        Some("supports") => {
+            // Supports all renderers.
+            return;
+        }
+        Some(arg) => {
+            eprintln!("unknown argument: {arg}");
+            std::process::exit(1);
+        }
+        None => {}
+    }
+
+    if let Err(e) = guide_helper::handle_preprocessing() {
+        eprintln!("{e:?}");
+        std::process::exit(1);
+    }
+}

guide/src/README.md

@@ -1,5 +1,22 @@
 # Introduction
 
+<style>
+    .mdbook-version {
+        position: absolute;
+        right: 20px;
+        top: 60px;
+        background-color: var(--theme-popup-bg);
+        border-radius: 8px;
+        padding: 2px 5px 2px 5px;
+        border: 1px solid var(--theme-popup-border);
+        font-size: 0.9em;
+    }
+</style>
+
+<div class="mdbook-version">
+Version: {{ mdbook-version }}
+</div>
+
 **mdBook** is a command line tool to create books with Markdown.
 It is ideal for creating product or API documentation, tutorials, course materials or anything that requires a clean,
 easily navigable and customizable presentation.

guide/src/continuous-integration.md

@@ -21,7 +21,7 @@ A simple approach would be to use the popular `curl` CLI tool to download the ex
 
 ```sh
 mkdir bin
-curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.52/mdbook-v0.4.52-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
+curl -sSL https://github.com/rust-lang/mdBook/releases/download/{{ mdbook-version }}/mdbook-{{ mdbook-version }}-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
 bin/mdbook build
 ```