Show the correct version in CI install docs

This fixes the version shown in the CI install docs when installing from
source by using the preprocessor similar to the prebuilt install docs.

Author: ehuss

guide/guide-helper/src/lib.rs

@@ -51,11 +51,30 @@ fn insert_version(book: &mut Book) {
         .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();
+    let version = Version::parse(manifest["package"]["version"].as_str().unwrap())
+        .expect("version is parseable");
     const MARKER: &str = "{{ mdbook-version }}";
+    const SEMVER_MARKER: &str = "{{ mdbook-semver }}";
+    const SEMVER_BREAK: &str = "{{ mdbook-semver-break }}";
     book.for_each_chapter_mut(|ch| {
         if ch.content.contains(MARKER) {
-            ch.content = ch.content.replace(MARKER, version);
+            ch.content = ch.content.replace(MARKER, &version.to_string());
+        }
+        if ch.content.contains(SEMVER_MARKER) {
+            let semver_version = if version.major == 0 {
+                format!("{}.{}", version.major, version.minor)
+            } else {
+                format!("{}", version.major)
+            };
+            ch.content = ch.content.replace(SEMVER_MARKER, &semver_version)
+        }
+        if ch.content.contains(SEMVER_BREAK) {
+            let semver_break = if version.major == 0 {
+                format!("{}.{}.0", version.major, version.minor + 1)
+            } else {
+                format!("{}.0.0", version.major + 1)
+            };
+            ch.content = ch.content.replace(SEMVER_BREAK, &semver_break);
         }
     });
 }

guide/src/continuous-integration.md

@@ -46,17 +46,18 @@ We recommend using a SemVer version specifier so that you get the latest **non-b
 For example:
 
 ```sh
-cargo install mdbook --no-default-features --features search --vers "^0.4" --locked
+cargo install mdbook --no-default-features --features search --vers "^{{ mdbook-version }}" --locked
 ```
 
 This includes several recommended options:
 
 * `--no-default-features` --- Disables features like the HTTP server used by `mdbook serve` that is likely not needed on CI.
   This will speed up the build time significantly.
 * `--features search` --- Disabling default features means you should then manually enable features that you want, such as the built-in [search] capability.
-* `--vers "^0.4"` --- This will install the most recent version of the `0.4` series.
-  However, versions after like `0.5.0` won't be installed, as they may break your build.
+* `--vers "^{{ mdbook-version }}"` --- This will install the most recent version of the `{{ mdbook-semver }}` version series.
+  However, semver-incompatible versions after like `{{ mdbook-semver-break }}` won't be installed, as they may break your build.
   Cargo will automatically upgrade mdBook if you have an older version already installed.
+  If you want to stick to a specific version of mdBook, replace the `^` with an `=`.
 * `--locked` --- This will use the dependencies that were used when mdBook was released.
   Without `--locked`, it will use the latest version of all dependencies, which may include some fixes since the last release, but may also (rarely) cause build problems.