diff --git a/Cargo.lock b/Cargo.lock index 1427d9d672..df36d277a4 100644 --- a/Cargo.lock +++ b/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" diff --git a/Cargo.toml b/Cargo.toml index e74b3915f2..c458b371f6 100644 --- a/Cargo.toml +++ b/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] diff --git a/guide/book.toml b/guide/book.toml index 1cb5357a16..d8863339a3 100644 --- a/guide/book.toml +++ b/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"] diff --git a/guide/guide-helper/Cargo.toml b/guide/guide-helper/Cargo.toml new file mode 100644 index 0000000000..840b6f915a --- /dev/null +++ b/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 diff --git a/guide/guide-helper/src/lib.rs b/guide/guide-helper/src/lib.rs new file mode 100644 index 0000000000..89cc935b72 --- /dev/null +++ b/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 { + 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); + } + }); +} diff --git a/guide/guide-helper/src/main.rs b/guide/guide-helper/src/main.rs new file mode 100644 index 0000000000..52d0207446 --- /dev/null +++ b/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); + } +} diff --git a/guide/src/README.md b/guide/src/README.md index a3aeb68df8..da6b16c55f 100644 --- a/guide/src/README.md +++ b/guide/src/README.md @@ -1,5 +1,22 @@ # Introduction + + +
+Version: {{ mdbook-version }} +
+ **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. diff --git a/guide/src/continuous-integration.md b/guide/src/continuous-integration.md index 8662c3c916..1abae6eb00 100644 --- a/guide/src/continuous-integration.md +++ b/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 ```