From 16ec185795ce39cec5d344636cc97568a05e4ab9 Mon Sep 17 00:00:00 2001
From: Ilya Grigoriev <ilyagr@users.noreply.github.com>
Date: Wed, 7 Feb 2024 12:09:39 -0800
Subject: [PATCH] docs, CLI reference: use `include-markdown` instead of a
 symlink

The main goal is to avoid having a symlink in our source tree. Currently, there
is no good way to work with the `jj` repo with `jj` on Windows.  Currently `jj`
just crashes with symlinks. This is being worked on, see e.g. #2939, but it will
always depend on whether Developer Mode is enabled in Windows or whether
symlinks are materialized as text files with symlinks. Finally, MkDocs has
trouble following symlinks on Windows, so building docs wouldn't work there.

Another advantage is that, previously, we were lucky that MkDocs treats `insta`
header in `cli-reference@.md.snap` as a Markdown header and follows symlinks at
all. Now, we no longer depend on that.
---
 cli/tests/cli-reference@.md.snap       |  7 +------
 cli/tests/test_generate_md_cli_help.rs |  7 +------
 docs/cli-reference.md                  | 20 +++++++++++++++++++-
 3 files changed, 21 insertions(+), 13 deletions(-)
 mode change 120000 => 100644 docs/cli-reference.md

diff --git a/cli/tests/cli-reference@.md.snap b/cli/tests/cli-reference@.md.snap
index c78cb8916e..61198885b9 100644
--- a/cli/tests/cli-reference@.md.snap
+++ b/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`
 
diff --git a/cli/tests/test_generate_md_cli_help.rs b/cli/tests/test_generate_md_cli_help.rs
index 4b69a8eb2e..a752a09ef2 100644
--- a/cli/tests/test_generate_md_cli_help.rs
+++ b/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-->
 
 "#;
 
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
deleted file mode 120000
index 57873d86bb..0000000000
--- a/docs/cli-reference.md
+++ /dev/null
@@ -1 +0,0 @@
-../cli/tests/cli-reference@.md.snap
\ No newline at end of file
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
new file mode 100644
index 0000000000..006789ce7a
--- /dev/null
+++ b/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-->"
+%}
+