Repository: axodotdev/cargo-dist
Pull request #256 (2023-05-13 00:50:27)

make mdbook better with toc's and link-checks
linkchecker is currently disabled due to https://github.com/axodotdev/oranda/issues/311


Patch:
diff --git a/.github/workflows/web.yml b/.github/workflows/web.yml
index 96ef5866..d3bccfc3 100644
--- a/.github/workflows/web.yml
+++ b/.github/workflows/web.yml
@@ -59,6 +59,7 @@ jobs:
         with:
           toolchain: stable
           override: true
+      - uses: swatinem/rust-cache@v2
 
       # OPTIONAL: build your mdbook
       # Note that "./book/" is the directory in our repo where the book.toml is
@@ -68,8 +69,13 @@ jobs:
       - name: Install mdbook
         run: |
           mkdir mdbook
-          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.14/mdbook-v0.4.14-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
+          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.27/mdbook-v0.4.27-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
           echo `pwd`/mdbook >> $GITHUB_PATH
+      # These could use binstall or caches...
+      - name: Install mdbook plugins
+        run: |
+          cargo install --locked mdbook-toc@0.11.2
+          cargo install --locked mdbook-linkcheck@0.7.7
       - name: Run mdbook build
         run: |
           mdbook build book
diff --git a/book/book.toml b/book/book.toml
index 9a781de7..52a8a415 100644
--- a/book/book.toml
+++ b/book/book.toml
@@ -8,3 +8,10 @@ title = "cargo-dist"
 [output.html]
 git-repository-url = "https://github.com/axodotdev/cargo-dist"
 edit-url-template = "https://github.com/axodotdev/cargo-dist/edit/main/book/{path}"
+
+# [output.linkcheck]
+# warning-policy = "error"
+
+[preprocessor.toc]
+command = "mdbook-toc"
+marker = "<!-- toc -->"
diff --git a/book/src/artifacts.md b/book/src/artifacts.md
index d873e86b..bd450f96 100644
--- a/book/src/artifacts.md
+++ b/book/src/artifacts.md
@@ -1,5 +1,7 @@
 # Artifacts
 
+<!-- toc -->
+
 cargo-dist's primary role is to produce "Artifacts", either to use locally or to upload as part of a release announcement. Here's a listing of the supported kinds!
 
 
@@ -31,7 +33,7 @@ This feature is currently disabled [pending a rework][rework-symbols], but basic
 
 Most other kinds of artifact are referred to as "installers", because they generally exist as ways of downloading and installing the binaries that were made for the executable-zips.
 
-[See the full docs on installers for details][installers-docs].
+[See the full docs on installers for details][installers].
 
 
 
diff --git a/book/src/cargo-release-guide.md b/book/src/cargo-release-guide.md
index d03bd939..bf3fc083 100644
--- a/book/src/cargo-release-guide.md
+++ b/book/src/cargo-release-guide.md
@@ -1,5 +1,7 @@
 # Using cargo-release
 
+<!-- toc -->
+
 > NOTE: It will be helpful to read [the section on cargo-dist Announcement Tags][announcements], because that is the interface boundary between cargo-release and cargo-dist. TL;DR: cargo-dist interprets a git tag of "v1.0.0" as "Announce/Release the whole workspace" (Unified Announcement) and "my-app-v1.0.0" as "Announce/Release that one package" (Singular Announcement).
 
 > NOTE: this guide assumes you're running [cargo-release v0.22.0][release-22] or greater, as that version made several significant changes to default behaviours (for the better!).
diff --git a/book/src/cli.md b/book/src/cli.md
index 2415e422..7c93c526 100644
--- a/book/src/cli.md
+++ b/book/src/cli.md
@@ -1,1 +1,7 @@
-{{#include ../../cargo-dist/tests/snapshots/cli_tests__markdown-help.snap:6:}}
\ No newline at end of file
+# cargo-dist CLI Manual
+
+<!-- toc -->
+
+{{#include ../../cargo-dist/tests/snapshots/cli_tests__markdown-help.snap:7:}}
+
+[workspace.metadata.dist]: ./config.md#metadatadist
\ No newline at end of file
diff --git a/book/src/concepts.md b/book/src/concepts.md
index ec080173..7aee2ba1 100644
--- a/book/src/concepts.md
+++ b/book/src/concepts.md
@@ -1,5 +1,7 @@
 # Concepts
 
+<!-- toc -->
+
 Here's the section where I use a bunch of words Capitalized Words to indicate they are a Special Concept in cargo-dist as I try to explain how it works. These are the "advanced" docs of cargo-dist, for the "beginner" docs see [the guide][guide] for the "beginner" docs.
 
 An invocation of cargo-dist has 4 major inputs:
diff --git a/book/src/config.md b/book/src/config.md
index 44a233a0..dec62fb0 100644
--- a/book/src/config.md
+++ b/book/src/config.md
@@ -1,5 +1,7 @@
 # Config
 
+<!-- toc -->
+
 cargo-dist accepts configuration from the following sources, in order of increasing preference (that is, CLI flags generally replace things specified in your Cargo.toml):
 
 * Relevant [Cargo.toml fields][cargo-manifest] like "repository" and "readme"
@@ -116,7 +118,7 @@ By default all runs of `cargo-dist` will be trying to handle all platforms speci
 
 Example: `installers = ["shell", "powershell"]`
 
-This is a list of installers you want to be made for your application(s). In principle this can be overridden on a per-package basis but that is not well tested. See [the full docs on installers for the full list of values][].
+This is a list of installers you want to be made for your application(s). In principle this can be overridden on a per-package basis but that is not well tested. See [the full docs on installers for the full list of values][installers].
 
 See "repository" for some discussion on the "Artifact Download URL".
 
diff --git a/book/src/install.md b/book/src/install.md
index ef05fa33..b600fa0d 100644
--- a/book/src/install.md
+++ b/book/src/install.md
@@ -1,5 +1,7 @@
 # Install
 
+<!-- toc -->
+
 Surprise! The tool for prebuilt shippable binaries has way too many ways to install it!
 Whichever way you choose to install it, it should be invocable as `cargo dist ...`. If you insist on invoking the binary directly as `cargo-dist` you must still add the extra `dist` arg and invoke it as `cargo-dist dist ...` (a quirk of the way cargo invokes subcommands).
 
diff --git a/book/src/installers.md b/book/src/installers.md
index b3c9e208..20fd6000 100644
--- a/book/src/installers.md
+++ b/book/src/installers.md
@@ -1,5 +1,7 @@
 # Installers
 
+<!-- toc -->
+
 The core functionality of cargo-dist is to build your binaries and produce tarballs/zips containing them. Basically every other kind of file it produces is considered an "installer" that helps download/install those binaries.
 
 > Currently all supported installers are "global"/"universal" installers that detect the current platform and download and unpack the appropriate tarball/zip. This currently requires CI support to be enabled so we can ensure the files are hosted somewhere and now where to fetch them from.
@@ -221,8 +223,7 @@ Although that's still missing things like [Windows crt-static workarounds][crt-s
 
 
 [issue-info-install]: https://github.com/axodotdev/cargo-dist/issues/72
-[issue-npm-readme]: https://github.com/axodotdev/cargo-dist/issues/238
-[issue-npm-install]: https://github.com/axodotdev/cargo-dist/issues/245
+[issue-npm-ci]: https://github.com/axodotdev/cargo-dist/issues/245
 [linux-pm-issue]: https://github.com/axodotdev/cargo-dist/issues/76
 [windows-pm-issue]: https://github.com/axodotdev/cargo-dist/issues/87
 [msi-installer-issue]: https://github.com/axodotdev/cargo-dist/issues/23
diff --git a/book/src/reference.md b/book/src/reference.md
index 72fc38da..8e6505dc 100644
--- a/book/src/reference.md
+++ b/book/src/reference.md
@@ -1,3 +1,3 @@
 # Reference
 
-The following sections are more focused on precise details.
\ No newline at end of file
+The following sections are more focused on precise details.
diff --git a/book/src/simple-guide.md b/book/src/simple-guide.md
index 9dee579a..8e731d0e 100644
--- a/book/src/simple-guide.md
+++ b/book/src/simple-guide.md
@@ -1,5 +1,7 @@
 # Guide: A Simple Application
 
+<!-- toc -->
+
 Let's start with the kind of simple [Cargo Workspace][workspace] you would get from `cargo new my-app` (or `cargo init my-app`): a single package that defines a [binary target][bin]. This is exactly the situation the [Way-Too-Quickstart][way-too-quickstart] should work perfectly for. Here we're going to take it a bit slower.
 
 Our goal will be to setup a Github CI workflow that announces a new release of our application with a Github Release. The workflow will also build our application for the 3 major desktop platforms, wrap the binaries in zips/tarballs, and upload them to the Github Release. The Github Release's text will also include the relevant release notes from our RELEASES.md file.
@@ -18,7 +20,7 @@ You can rerun `init` as many times as you want, as it also functions as an "upda
 cargo dist init
 ```
 
-[`init`][] on its own just edits your Cargo.toml to include the recommended defaults. If you have enabled CI support, it will also run `cargo dist generate-ci` after setting things up. This ensures your config and your CI scripts are in sync, but will unfortunately clobber any hand-edits you made to the scripts.
+[`init`][init] on its own just edits your Cargo.toml to include the recommended defaults. If you have enabled CI support, it will also run `cargo dist generate-ci` after setting things up. This ensures your config and your CI scripts are in sync, but will unfortunately clobber any hand-edits you made to the scripts.
 
 Let's look at those defaults that were added (yes those comments are generated too, you will never stop me from adding more docs!!!):
 
diff --git a/book/src/way-too-quickstart.md b/book/src/way-too-quickstart.md
index ef236304..d4ce9d5f 100644
--- a/book/src/way-too-quickstart.md
+++ b/book/src/way-too-quickstart.md
@@ -1,15 +1,11 @@
 # Way-Too-Quickstart
 
+<!-- toc -->
+
 > TLDR: cargo-dist is a souped up version of `cargo build` which handles building tarballs/zips and [installers][]. It also knows how to generate Github CI for orchestrating itself and uploading its output to a new Github Release. You can use cargo-dist if you don't care about that CI stuff, but this guide assumes that you do.
 >
 > This quickstart is a bit *too* quick because there's some important nuances to "announcing and building releases" that depend on the way you like to structure and version your workspace. We will blatantly ignore those nuances and show you the Happiest Happy Path (a workspace with one crate that defines a binary). Checkout [the guide][guide] for more details on what you should *actually* do.
 
-The quickstart has three parts: 
-
-1. setting up cargo-dist
-2. testing locally
-3. cutting a release of your project on Github
-
 
 
 ## Setup
diff --git a/book/src/workspace-guide.md b/book/src/workspace-guide.md
index 88c3a096..352c8c9d 100644
--- a/book/src/workspace-guide.md
+++ b/book/src/workspace-guide.md
@@ -1,5 +1,7 @@
 # Guide: More Complex Workspaces
 
+<!-- toc -->
+
 Now that we've [looked at a simple example][simple-guide] with `cargo new`, let's start looking at ways to make a [Cargo Workspace][workspace] more complicated, and how cargo-dist will deal with them.
 
 But first, let's define some precise terminology: 
diff --git a/cargo-dist/oranda.json b/cargo-dist/oranda.json
index 7e88916a..cd9594b0 100644
--- a/cargo-dist/oranda.json
+++ b/cargo-dist/oranda.json
@@ -8,7 +8,7 @@
     "image_alt": "axo",
     "twitter_account": "@axodotdev"
   },
-  "md_book": "../book/book",
+  "md_book": "../book/book/",
   "artifacts": {
     "cargo_dist": true,
     "package_managers": {
diff --git a/cargo-dist/src/cli.rs b/cargo-dist/src/cli.rs
index 6c703118..3735419a 100644
--- a/cargo-dist/src/cli.rs
+++ b/cargo-dist/src/cli.rs
@@ -146,7 +146,7 @@ pub enum Commands {
     /// (although it adds --output-format=json so that it's machine-readable).
     ///
     /// This is an alias for the lower-level 'manifest' command with the
-    /// appropriate flags forced for asking for "everything":
+    /// appropriate flags forced for asking for "everything"
     ///
     ///     cargo dist manifest --artifacts=all --no-local-paths
     ///
diff --git a/cargo-dist/src/main.rs b/cargo-dist/src/main.rs
index 68bdd5f1..b496a321 100644
--- a/cargo-dist/src/main.rs
+++ b/cargo-dist/src/main.rs
@@ -297,9 +297,9 @@ fn print_help_markdown(out: &mut dyn Write) -> std::io::Result<()> {
         let mut in_normal_options = false;
         for line in lines {
             if let Some(usage) = line.strip_prefix("Usage: ") {
-                writeln!(out, "### Usage:")?;
+                writeln!(out, "### Usage")?;
                 writeln!(out)?;
-                writeln!(out, "```")?;
+                writeln!(out, "```text")?;
                 writeln!(out, "{usage}")?;
                 writeln!(out, "```")?;
                 continue;


Test patch:
diff --git a/cargo-dist/tests/snapshots/cli_tests__markdown-help.snap b/cargo-dist/tests/snapshots/cli_tests__markdown-help.snap
index 66edcefb..2238482c 100644
--- a/cargo-dist/tests/snapshots/cli_tests__markdown-help.snap
+++ b/cargo-dist/tests/snapshots/cli_tests__markdown-help.snap
@@ -11,9 +11,9 @@ Shippable packaging for Rust.
 
 When run without a subcommand, `cargo dist` will invoke the `build` subcommand. See `cargo dist help build` for more details.
 
-### Usage:
+### Usage
 
-```
+```text
 cargo dist [OPTIONS]
 ```
 cargo dist <COMMAND>
@@ -89,9 +89,9 @@ In the future we may try to make this look at the current git tags or something?
 ## cargo dist build
 Build artifacts
 
-### Usage:
+### Usage
 
-```
+```text
 cargo dist build [OPTIONS]
 ```
 
@@ -127,9 +127,9 @@ Setup or update cargo-dist
 
 This will interactively guide you through the process of selecting configuration options and will also automatically run 'cargo dist generate-ci' afterwards as necessary. It will also handle updating your project to a new version of cargo-dist if you're running one.
 
-### Usage:
+### Usage
 
-```
+```text
 cargo dist init [OPTIONS]
 ```
 
@@ -152,9 +152,9 @@ This subcommand accepts all the [global options](#global-options)
 ## cargo dist generate-ci
 Generate CI scripts for orchestrating cargo-dist
 
-### Usage:
+### Usage
 
-```
+```text
 cargo dist generate-ci [OPTIONS]
 ```
 
@@ -175,9 +175,9 @@ Notably it will default to only talking about artifacts for the host system, and
 
 'cargo dist plan' is an alias for this command that picks nicer defaults by forcing a couple flags to have specific values. You probably want that.
 
-### Usage:
+### Usage
 
-```
+```text
 cargo dist manifest [OPTIONS]
 ```
 
@@ -213,13 +213,13 @@ Get a plan of what to build (and check project status)
 
 If you want to know what running your cargo-dist CI will produce, this is the command for you! This is the exact command that CI will run to make its build plan and generate dist-manifest.json (although it adds --output-format=json so that it's machine-readable).
 
-### This is an alias for the lower-level 'manifest' command with the appropriate flags forced for asking for "everything"
+This is an alias for the lower-level 'manifest' command with the appropriate flags forced for asking for "everything"
 
 cargo dist manifest --artifacts=all --no-local-paths
 
-### Usage:
+### Usage
 
-```
+```text
 cargo dist plan [OPTIONS]
 ```
 
@@ -234,9 +234,9 @@ This subcommand accepts all the [global options](#global-options)
 ## cargo dist help
 Print this message or the help of the given subcommand(s)
 
-### Usage:
+### Usage
 
-```
+```text
 cargo dist help [COMMAND]
 ```