Merge pull request #3154 from ehuss/ci-version-string

Show the correct version in CI 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.