Clean up the generated CLI reference and remove the need fo a symlink using the include-markdown plugin

cli/tests/cli-reference@.md.snap

@@ -3,12 +3,7 @@ source: cli/tests/test_generate_md_cli_help.rs
 description: "AUTO-GENERATED FILE, DO NOT EDIT. This cli reference is generated as an `insta` snapshot. MkDocs follows they symlink from docs/cli-reference.md to the snap. Unfortunately, `insta` unavoidably creates this header. Luckily, MkDocs ignores the header since it has the same format as Markdown headers. TODO: MkDocs may fail on Windows if symlinks are not enabled in the OS settings"
 ---
 
-!!! warning
-
-    This CLI reference is experimental. It is automatically generated, but
-    does not match the `jj help` output exactly.
-
-    <!-- See also https://github.com/ConnorGray/clap-markdown/issues -->
+<!-- BEGIN MARKDOWN-->
 
 # Command-Line Help for `jj`
 

cli/tests/test_generate_md_cli_help.rs

@@ -17,12 +17,7 @@ use insta::assert_snapshot;
 use crate::common::TestEnvironment;
 
 const PREAMBLE: &str = r#"
-!!! warning
-
-    This CLI reference is experimental. It is automatically generated, but
-    does not match the `jj help` output exactly.
-
-    <!-- See also https://github.com/ConnorGray/clap-markdown/issues -->
+<!-- BEGIN MARKDOWN-->
 
 "#;
 

docs/cli-reference.md

@@ -0,0 +1,19 @@
+<!-- The contents of the CLI reference is auto-generated by a Rust test.
+ --- If `cargo insta` is installed, you can regenerate the CLI reference with:
+ ---      cargo insta test --accept --workspace -- test_generate
+ -->
+
+!!! warning
+
+    This CLI reference is experimental. It is automatically generated, but
+    does not match the `jj help` output exactly.
+
+    <!-- See also https://github.com/ConnorGray/clap-markdown/issues -->
+
+
+{%
+  include-markdown "../cli/tests/cli-reference@.md.snap"
+  rewrite-relative-urls=false
+  start="<!-- BEGIN MARKDOWN-->"
+%}
+

mkdocs-offline.yml

@@ -4,6 +4,14 @@
 INHERIT: 'mkdocs.yml'
 plugins:
     - offline
+
+    # For now, *every plugin config* from `mkdocs.yml` has to be repeated here.
+    # https://github.com/mondeja/mkdocs-include-markdown-plugin/issues/195#issuecomment-1933085478
+    # https://github.com/mkdocs/mkdocs/issues/3216
+    - include-markdown # For the CLI reference
+    - search
+    - redirects:
+        redirect_maps:
 # Turns out the `offline` plugin forces the following
 # option no matter what, and therefore shouldn't be
 # used in the main config file.

mkdocs.yml

@@ -31,7 +31,11 @@ theme:
 extra:
   version:
     provider: mike
+
+# IMPORTANT: any changes to plugins have to be duplicated in
+# `mkdocs-offline.yml`. See that file for more details.
 plugins:
+    - include-markdown # For the CLI reference
     - search
     - redirects:
         redirect_maps:

pyproject.toml

@@ -21,6 +21,7 @@ mdx-breakless-lists = "^1.0.1"
 mkdocs-redirects = "^1.2.1"
 # Versioning of documentation
 mike = "^2.0.0"
+mkdocs-include-markdown-plugin = "^6.0.4"
 
 [build-system]
 requires = ["poetry-core>=1.0.0"]