From 77ed2f879a8076e15966a15148d89cbd675b2b09 Mon Sep 17 00:00:00 2001
From: jdx <216188+jdx@users.noreply.github.com>
Date: Sat, 14 Dec 2024 10:41:25 -0600
Subject: [PATCH] feat: feature for automatically adding code fences (#197)

---
 cli/src/cli/generate/markdown.rs              |   7 +-
 cli/usage.usage.kdl                           |   1 +
 docs/cli/reference/bash.md                    |   7 -
 docs/cli/reference/commands.json              |   8 +
 docs/cli/reference/generate/markdown.md       |   2 +
 examples/docs/MISE_INLINE.md                  |   4 -
 examples/docs/MISE_MULTI.md                   |   4 -
 ...omplete__bash__tests__complete_bash-3.snap |   5 +-
 ...omplete__fish__tests__complete_fish-3.snap |   7 +-
 ..._complete__zsh__tests__complete_zsh-3.snap |   7 +-
 lib/src/docs/markdown/arg.rs                  |  18 +-
 lib/src/docs/markdown/cmd.rs                  |  30 +-
 lib/src/docs/markdown/flag.rs                 |  16 +-
 lib/src/docs/markdown/renderer.rs             |  58 +++-
 lib/src/docs/markdown/spec.rs                 |  18 +-
 .../markdown/templates/arg_template.md.tera   |   6 +-
 .../markdown/templates/cmd_template.md.tera   |  20 +-
 .../markdown/templates/flag_template.md.tera  |   5 +-
 lib/src/docs/mod.rs                           |   1 +
 lib/src/docs/models.rs                        | 313 ++++++++++++++++++
 lib/src/lib.rs                                |   1 +
 lib/src/test.rs                               |  23 +-
 mise.toml                                     |   6 +-
 23 files changed, 484 insertions(+), 83 deletions(-)
 create mode 100644 lib/src/docs/models.rs

diff --git a/cli/src/cli/generate/markdown.rs b/cli/src/cli/generate/markdown.rs
index 605541d0..2ea07e0a 100644
--- a/cli/src/cli/generate/markdown.rs
+++ b/cli/src/cli/generate/markdown.rs
@@ -25,6 +25,9 @@ pub struct Markdown {
     #[clap(long)]
     html_encode: bool,
 
+    #[clap(long)]
+    replace_pre_with_code_fences: bool,
+
     /// Output markdown files to this directory
     #[clap(long, value_hint = clap::ValueHint::DirPath)]
     out_dir: Option<PathBuf>,
@@ -41,7 +44,9 @@ impl Markdown {
             Ok(())
         };
         let (spec, _) = Spec::parse_file(&self.file)?;
-        let mut ctx = MarkdownRenderer::new(&spec).with_html_encode(self.html_encode);
+        let mut ctx = MarkdownRenderer::new(spec.clone())
+            .with_html_encode(self.html_encode)
+            .with_replace_pre_with_code_fences(self.replace_pre_with_code_fences);
         if let Some(url_prefix) = &self.url_prefix {
             ctx = ctx.with_url_prefix(url_prefix);
         }
diff --git a/cli/usage.usage.kdl b/cli/usage.usage.kdl
index 77da4706..98dceec1 100644
--- a/cli/usage.usage.kdl
+++ b/cli/usage.usage.kdl
@@ -92,6 +92,7 @@ cmd "generate" subcommand_required=true {
             arg "<URL_PREFIX>"
         }
         flag "--html-encode" help="Escape HTML in markdown"
+        flag "--replace-pre-with-code-fences"
         flag "--out-dir" help="Output markdown files to this directory" {
             arg "<OUT_DIR>"
         }
diff --git a/docs/cli/reference/bash.md b/docs/cli/reference/bash.md
index 183296fb..ce45dced 100644
--- a/docs/cli/reference/bash.md
+++ b/docs/cli/reference/bash.md
@@ -14,13 +14,6 @@ to properly escape and quote values with spaces in them.
 
 ### `<SCRIPT>`
 
-Executes a bash script
-
-Typically, this will be called by a script's shebang
-
-If using `var=true` on args/flags, they will be joined with spaces using `shell_words::join()`
-to properly escape and quote values with spaces in them.
-
 ### `[ARGS]...`
 
 arguments to pass to script
diff --git a/docs/cli/reference/commands.json b/docs/cli/reference/commands.json
index 2bae7b83..fa354b41 100644
--- a/docs/cli/reference/commands.json
+++ b/docs/cli/reference/commands.json
@@ -448,6 +448,14 @@
                 "hide": false,
                 "global": false
               },
+              {
+                "name": "replace-pre-with-code-fences",
+                "usage": "--replace-pre-with-code-fences",
+                "short": [],
+                "long": ["replace-pre-with-code-fences"],
+                "hide": false,
+                "global": false
+              },
               {
                 "name": "out-dir",
                 "usage": "--out-dir <OUT_DIR>",
diff --git a/docs/cli/reference/generate/markdown.md b/docs/cli/reference/generate/markdown.md
index 364e8c3c..fba0460e 100644
--- a/docs/cli/reference/generate/markdown.md
+++ b/docs/cli/reference/generate/markdown.md
@@ -22,6 +22,8 @@ Prefix to add to all URLs
 
 Escape HTML in markdown
 
+### `--replace-pre-with-code-fences`
+
 ### `--out-dir <OUT_DIR>`
 
 Output markdown files to this directory
diff --git a/examples/docs/MISE_INLINE.md b/examples/docs/MISE_INLINE.md
index f6ec0c31..28b679fa 100644
--- a/examples/docs/MISE_INLINE.md
+++ b/examples/docs/MISE_INLINE.md
@@ -433,8 +433,6 @@ If not provided, the nearest mise.toml file will be used
 
 #### `-t --type <TYPE>`
 
-Display the value of a setting in a mise.toml file
-
 **Choices:**
 
 - `string`
@@ -738,8 +736,6 @@ root directory to search for tasks
 
 #### `-s --style <STYLE>`
 
-[experimental] Generate documentation for tasks in a project
-
 **Choices:**
 
 - `simple`
diff --git a/examples/docs/MISE_MULTI.md b/examples/docs/MISE_MULTI.md
index f6ec0c31..28b679fa 100644
--- a/examples/docs/MISE_MULTI.md
+++ b/examples/docs/MISE_MULTI.md
@@ -433,8 +433,6 @@ If not provided, the nearest mise.toml file will be used
 
 #### `-t --type <TYPE>`
 
-Display the value of a setting in a mise.toml file
-
 **Choices:**
 
 - `string`
@@ -738,8 +736,6 @@ root directory to search for tasks
 
 #### `-s --style <STYLE>`
 
-[experimental] Generate documentation for tasks in a project
-
 **Choices:**
 
 - `simple`
diff --git a/lib/src/complete/snapshots/usage__complete__bash__tests__complete_bash-3.snap b/lib/src/complete/snapshots/usage__complete__bash__tests__complete_bash-3.snap
index a832e9b5..df878979 100644
--- a/lib/src/complete/snapshots/usage__complete__bash__tests__complete_bash-3.snap
+++ b/lib/src/complete/snapshots/usage__complete__bash__tests__complete_bash-3.snap
@@ -17,7 +17,7 @@ bin "mycli"
 source_code_link_template "https://github.com/jdx/mise/blob/main/src/cli/{{path}}.rs"
 flag "--flag1" help="flag1 description"
 flag "--flag2" help="flag2 description" {
-    long_help "flag2 long description"
+    long_help "flag2 long description\n\nincludes a code block:\n\n    $ echo hello world\n    hello world\n    \n    more code\n\nsome docs\n\n    $ echo hello world\n    hello world\n"
 }
 flag "--flag3" help="flag3 description" negate="--no-flag3"
 flag "--with-default"
@@ -36,7 +36,8 @@ arg "[with-default]" default="default value"
 complete "plugin" run="echo \"plugin-1\nplugin-2\nplugin-3\""
 cmd "plugin" {
     cmd "install" {
-        flag "-g --global"
+        long_help r"install a plugin"
+        flag "-g --global" global=true
         flag "-d --dir" {
             arg "<dir>"
         }
diff --git a/lib/src/complete/snapshots/usage__complete__fish__tests__complete_fish-3.snap b/lib/src/complete/snapshots/usage__complete__fish__tests__complete_fish-3.snap
index 53c937ac..1f44a694 100644
--- a/lib/src/complete/snapshots/usage__complete__fish__tests__complete_fish-3.snap
+++ b/lib/src/complete/snapshots/usage__complete__fish__tests__complete_fish-3.snap
@@ -1,6 +1,6 @@
 ---
 source: lib/src/complete/fish.rs
-expression: "complete_fish(&CompleteOptions\n{\n    shell: \"fish\".to_string(), bin: \"mycli\".to_string(), cache_key: None,\n    spec: Some(SPEC_KITCHEN_SINK.clone()), usage_cmd: None,\n})"
+expression: "complete_fish(&CompleteOptions\n{\n    shell: \"fish\".to_string(), bin: \"mycli\".to_string(), cache_key: None,\n    spec: Some(SPEC_KITCHEN_SINK.clone()), usage_cmd: None,\n    include_bash_completion_lib: false,\n})"
 snapshot_kind: text
 ---
 # if "usage" is not installed show an error
@@ -16,7 +16,7 @@ bin "mycli"
 source_code_link_template "https://github.com/jdx/mise/blob/main/src/cli/{{path}}.rs"
 flag "--flag1" help="flag1 description"
 flag "--flag2" help="flag2 description" {
-    long_help "flag2 long description"
+    long_help "flag2 long description\n\nincludes a code block:\n\n    $ echo hello world\n    hello world\n    \n    more code\n\nsome docs\n\n    $ echo hello world\n    hello world\n"
 }
 flag "--flag3" help="flag3 description" negate="--no-flag3"
 flag "--with-default"
@@ -35,7 +35,8 @@ arg "[with-default]" default="default value"
 complete "plugin" run="echo \"plugin-1\nplugin-2\nplugin-3\""
 cmd "plugin" {
     cmd "install" {
-        flag "-g --global"
+        long_help r"install a plugin"
+        flag "-g --global" global=true
         flag "-d --dir" {
             arg "<dir>"
         }
diff --git a/lib/src/complete/snapshots/usage__complete__zsh__tests__complete_zsh-3.snap b/lib/src/complete/snapshots/usage__complete__zsh__tests__complete_zsh-3.snap
index a82a4f27..2e5475c2 100644
--- a/lib/src/complete/snapshots/usage__complete__zsh__tests__complete_zsh-3.snap
+++ b/lib/src/complete/snapshots/usage__complete__zsh__tests__complete_zsh-3.snap
@@ -1,6 +1,6 @@
 ---
 source: lib/src/complete/zsh.rs
-expression: "complete_zsh(&CompleteOptions\n{\n    shell: \"zsh\".to_string(), bin: \"mycli\".to_string(), cache_key: None, spec:\n    Some(SPEC_KITCHEN_SINK.clone()), usage_cmd: None,\n})"
+expression: "complete_zsh(&CompleteOptions\n{\n    shell: \"zsh\".to_string(), bin: \"mycli\".to_string(), cache_key: None, spec:\n    Some(SPEC_KITCHEN_SINK.clone()), usage_cmd: None,\n    include_bash_completion_lib: false,\n})"
 snapshot_kind: text
 ---
 #compdef mycli
@@ -22,7 +22,7 @@ bin "mycli"
 source_code_link_template "https://github.com/jdx/mise/blob/main/src/cli/{{path}}.rs"
 flag "--flag1" help="flag1 description"
 flag "--flag2" help="flag2 description" {
-    long_help "flag2 long description"
+    long_help "flag2 long description\n\nincludes a code block:\n\n    $ echo hello world\n    hello world\n    \n    more code\n\nsome docs\n\n    $ echo hello world\n    hello world\n"
 }
 flag "--flag3" help="flag3 description" negate="--no-flag3"
 flag "--with-default"
@@ -41,7 +41,8 @@ arg "[with-default]" default="default value"
 complete "plugin" run="echo \"plugin-1\nplugin-2\nplugin-3\""
 cmd "plugin" {
     cmd "install" {
-        flag "-g --global"
+        long_help r"install a plugin"
+        flag "-g --global" global=true
         flag "-d --dir" {
             arg "<dir>"
         }
diff --git a/lib/src/docs/markdown/arg.rs b/lib/src/docs/markdown/arg.rs
index 7de36016..916eab01 100644
--- a/lib/src/docs/markdown/arg.rs
+++ b/lib/src/docs/markdown/arg.rs
@@ -1,11 +1,13 @@
 use crate::docs::markdown::renderer::MarkdownRenderer;
+use crate::docs::models::SpecArg;
 use crate::error::UsageErr;
-use crate::SpecArg;
 
-impl MarkdownRenderer<'_> {
-    pub fn render_arg(&self, arg: &SpecArg) -> Result<String, UsageErr> {
+impl MarkdownRenderer {
+    pub fn render_arg(&self, arg: &crate::SpecArg) -> Result<String, UsageErr> {
+        let mut arg = SpecArg::from(arg);
+        arg.render_md(self);
         let mut ctx = self.clone();
-        ctx.insert("arg", arg);
+        ctx.insert("arg", &arg);
         ctx.render("arg_template.md.tera")
     }
 }
@@ -19,11 +21,7 @@ mod tests {
     #[test]
     fn test_render_markdown_arg() {
         let spec = spec! { r#"arg "arg1" help="arg1 description""# }.unwrap();
-        let ctx = MarkdownRenderer::new(&spec);
-        assert_snapshot!(ctx.render_arg(&spec.cmd.args[0]).unwrap(), @r#"
-
-
-        arg1 description
-        "#);
+        let ctx = MarkdownRenderer::new(spec.clone());
+        assert_snapshot!(ctx.render_arg(&spec.cmd.args[0]).unwrap(), @"arg1 description");
     }
 }
diff --git a/lib/src/docs/markdown/cmd.rs b/lib/src/docs/markdown/cmd.rs
index e4ddc2a2..e7707f2b 100644
--- a/lib/src/docs/markdown/cmd.rs
+++ b/lib/src/docs/markdown/cmd.rs
@@ -1,11 +1,13 @@
 use crate::docs::markdown::renderer::MarkdownRenderer;
+use crate::docs::models::SpecCommand;
 use crate::error::UsageErr;
-use crate::SpecCommand;
 
-impl MarkdownRenderer<'_> {
-    pub fn render_cmd(&self, cmd: &SpecCommand) -> Result<String, UsageErr> {
+impl MarkdownRenderer {
+    pub fn render_cmd(&self, cmd: &crate::SpecCommand) -> Result<String, UsageErr> {
+        let mut cmd = SpecCommand::from(cmd);
+        cmd.render_md(self);
         let mut ctx = self.clone();
-        ctx.insert("cmd", cmd);
+        ctx.insert("cmd", &cmd);
         ctx.render("cmd_template.md.tera")
     }
 }
@@ -18,7 +20,9 @@ mod tests {
 
     #[test]
     fn test_render_markdown_cmd() {
-        let ctx = MarkdownRenderer::new(&SPEC_KITCHEN_SINK).with_multi(true);
+        let ctx = MarkdownRenderer::new(SPEC_KITCHEN_SINK.clone())
+            .with_multi(true)
+            .with_replace_pre_with_code_fences(true);
         assert_snapshot!(ctx.render_cmd(&SPEC_KITCHEN_SINK.cmd).unwrap(), @r"
         # `mycli`
 
@@ -62,6 +66,22 @@ mod tests {
 
         flag2 long description
 
+        includes a code block:
+
+        ```
+        $ echo hello world
+        hello world
+
+        more code
+        ```
+
+        some docs
+
+        ```
+        $ echo hello world
+        hello world
+        ```
+
         ### `--flag3`
 
         flag3 description
diff --git a/lib/src/docs/markdown/flag.rs b/lib/src/docs/markdown/flag.rs
index a53d6c48..db86718d 100644
--- a/lib/src/docs/markdown/flag.rs
+++ b/lib/src/docs/markdown/flag.rs
@@ -1,9 +1,11 @@
 use crate::docs::markdown::renderer::MarkdownRenderer;
+use crate::docs::models::SpecFlag;
 use crate::error::UsageErr;
-use crate::SpecFlag;
 
-impl MarkdownRenderer<'_> {
-    pub fn render_flag(&self, flag: &SpecFlag) -> Result<String, UsageErr> {
+impl MarkdownRenderer {
+    pub fn render_flag(&self, flag: &crate::SpecFlag) -> Result<String, UsageErr> {
+        let mut flag = SpecFlag::from(flag);
+        flag.render_md(self);
         let mut ctx = self.clone();
         ctx.insert("flag", &flag);
         ctx.render("flag_template.md.tera")
@@ -19,11 +21,7 @@ mod tests {
     #[test]
     fn test_render_markdown_flag() {
         let spec = spec! { r#"flag "--flag1" help="flag1 description""# }.unwrap();
-        let ctx = MarkdownRenderer::new(&spec);
-        assert_snapshot!(ctx.render_flag(&spec.cmd.flags[0]).unwrap(), @r#"
-
-
-        flag1 description
-        "#);
+        let ctx = MarkdownRenderer::new(spec.clone()).with_replace_pre_with_code_fences(true);
+        assert_snapshot!(ctx.render_flag(&spec.cmd.flags[0]).unwrap(), @"flag1 description");
     }
 }
diff --git a/lib/src/docs/markdown/renderer.rs b/lib/src/docs/markdown/renderer.rs
index 8065a56e..0ee7e3df 100644
--- a/lib/src/docs/markdown/renderer.rs
+++ b/lib/src/docs/markdown/renderer.rs
@@ -1,31 +1,37 @@
 use crate::docs::markdown::tera::TERA;
+use crate::docs::models::Spec;
 use crate::error::UsageErr;
-use crate::Spec;
 use itertools::Itertools;
 use serde::Serialize;
 use std::collections::HashMap;
 use xx::regex;
 
 #[derive(Debug, Clone)]
-pub struct MarkdownRenderer<'a> {
-    pub(crate) spec: &'a Spec,
+pub struct MarkdownRenderer {
+    pub(crate) spec: Spec,
     pub(crate) header_level: usize,
     pub(crate) multi: bool,
     tera_ctx: tera::Context,
     url_prefix: Option<String>,
     html_encode: bool,
+    replace_pre_with_code_fences: bool,
 }
 
-impl<'a> MarkdownRenderer<'a> {
-    pub fn new(spec: &'a Spec) -> Self {
-        Self {
-            spec,
+impl MarkdownRenderer {
+    pub fn new(spec: crate::Spec) -> Self {
+        let mut renderer = Self {
+            spec: spec.into(),
             header_level: 1,
             multi: false,
             tera_ctx: tera::Context::new(),
             url_prefix: None,
             html_encode: true,
-        }
+            replace_pre_with_code_fences: false,
+        };
+        let mut spec = renderer.spec.clone();
+        spec.render_md(&renderer);
+        renderer.spec = spec;
+        renderer
     }
 
     pub fn with_header_level(mut self, header_level: usize) -> Self {
@@ -48,13 +54,18 @@ impl<'a> MarkdownRenderer<'a> {
         self
     }
 
+    pub fn with_replace_pre_with_code_fences(mut self, replace_pre_with_code_fences: bool) -> Self {
+        self.replace_pre_with_code_fences = replace_pre_with_code_fences;
+        self
+    }
+
     pub(crate) fn insert<T: Serialize + ?Sized, S: Into<String>>(&mut self, key: S, val: &T) {
         self.tera_ctx.insert(key, val);
     }
 
     fn tera_ctx(&self) -> tera::Context {
         let mut ctx = self.tera_ctx.clone();
-        ctx.insert("spec", self.spec);
+        ctx.insert("spec", &self.spec);
         ctx.insert("header_level", &self.header_level);
         ctx.insert("multi", &self.multi);
         ctx.insert("url_prefix", &self.url_prefix);
@@ -126,4 +137,33 @@ impl<'a> MarkdownRenderer<'a> {
 
         Ok(tera.render(template_name, &self.tera_ctx())?)
     }
+
+    pub(crate) fn replace_code_fences(&self, md: String) -> String {
+        if !self.replace_pre_with_code_fences {
+            return md;
+        }
+        // TODO: handle fences inside of <pre> or <code>
+        let mut in_code_block = false;
+        let mut new_md = String::new();
+        for line in md.lines() {
+            if let Some(line) = line.strip_prefix("    ") {
+                if in_code_block {
+                    new_md.push_str(&format!("{}\n", line));
+                } else {
+                    new_md.push_str(&format!("```\n{}\n", line));
+                    in_code_block = true;
+                }
+            } else {
+                if in_code_block {
+                    new_md.push_str("```\n");
+                    in_code_block = false;
+                }
+                new_md.push_str(&format!("{}\n", line));
+            }
+        }
+        if in_code_block {
+            new_md.push_str("```\n");
+        }
+        new_md
+    }
 }
diff --git a/lib/src/docs/markdown/spec.rs b/lib/src/docs/markdown/spec.rs
index ea63d7b8..b662a2a7 100644
--- a/lib/src/docs/markdown/spec.rs
+++ b/lib/src/docs/markdown/spec.rs
@@ -1,7 +1,7 @@
 use crate::docs::markdown::renderer::MarkdownRenderer;
 use crate::error::UsageErr;
 
-impl MarkdownRenderer<'_> {
+impl MarkdownRenderer {
     pub fn render_spec(&self) -> Result<String, UsageErr> {
         let mut ctx = self.clone();
         ctx.insert("all_commands", &self.spec.cmd.all_subcommands());
@@ -24,7 +24,7 @@ mod tests {
 
     #[test]
     fn test_render_markdown_spec() {
-        let ctx = MarkdownRenderer::new(&SPEC_KITCHEN_SINK);
+        let ctx = MarkdownRenderer::new(SPEC_KITCHEN_SINK.clone());
         assert_snapshot!(ctx.render_spec().unwrap(), @r"
         # `mycli`
 
@@ -68,6 +68,18 @@ mod tests {
 
         flag2 long description
 
+        includes a code block:
+
+            $ echo hello world
+            hello world
+            
+            more code
+
+        some docs
+
+            $ echo hello world
+            hello world
+
         ### `--flag3`
 
         flag3 description
@@ -94,6 +106,8 @@ mod tests {
         - **Usage**: `mycli plugin install [FLAGS] <plugin> <version>`
         - **Source code**: [`src/cli/plugin/install.rs`](https://github.com/jdx/mise/blob/main/src/cli/plugin/install.rs)
 
+        install a plugin
+
         ### Arguments
 
         #### `<plugin>`
diff --git a/lib/src/docs/markdown/templates/arg_template.md.tera b/lib/src/docs/markdown/templates/arg_template.md.tera
index 08d94a4a..70f3e470 100644
--- a/lib/src/docs/markdown/templates/arg_template.md.tera
+++ b/lib/src/docs/markdown/templates/arg_template.md.tera
@@ -1,8 +1,6 @@
-{%- if arg.help_long_md %}{% set help = arg.long_help %}{% elif arg.help_long %}{% set help = arg.help_long %}{% elif arg.help %}{% set help = arg.help %}{% endif %}
+{%- if arg.help_md %}
 
-{%- if help %}
-
-{{ help | escape_md }}
+{{ arg.help_md | escape_md }}
 {%- endif %}
 {%- if arg.choices %}
 
diff --git a/lib/src/docs/markdown/templates/cmd_template.md.tera b/lib/src/docs/markdown/templates/cmd_template.md.tera
index 1fdbd918..d3de8fb8 100644
--- a/lib/src/docs/markdown/templates/cmd_template.md.tera
+++ b/lib/src/docs/markdown/templates/cmd_template.md.tera
@@ -1,14 +1,11 @@
 {%- set source_code_link = source_code_link(spec=spec, cmd=cmd) %}
-{%- if cmd.before_help_md %}{% set before_help = cmd.before_help_md %}{% elif cmd.before_help_long %}{% set before_help = cmd.before_help_long %}{% elif cmd.before_help %}{% set before_help = cmd.before_help %}{% endif %}
-{%- if cmd.help_md %}{% set help = cmd.help_md %}{% elif cmd.help_long %}{% set help = cmd.help_long %}{% elif cmd.help %}{% set help = cmd.help %}{% else %}{% set help = "" %}{% endif %}
-{%- if cmd.after_help_md %}{% set after_help = cmd.after_help_md %}{% elif cmd.after_help_long %}{% set after_help = cmd.after_help_long %}{% elif cmd.after_help %}{% set after_help = cmd.after_help %}{% endif %}
 {%- set full_cmd = cmd.full_cmd | join(sep=" ") %}
 {%- if multi -%}
 {{- "#" | repeat(count=header_level) }} `{{ spec.bin ~ " " ~ full_cmd | trim }}`
 {%- endif %}
-{%- if before_help %}
+{%- if cmd.before_help_md %}
 
-{{ before_help | escape_md }}
+{{ cmd.before_help_md | escape_md }}
 {%- endif %}
 
 - **Usage**: `{{ spec.bin ~ " " ~ cmd.usage | trim }}`
@@ -19,15 +16,20 @@
 - **Source code**: {{ source_code_link }}
 {%- endif %}
 
-{%- if help %}
+{%- if cmd.help_md %}
 
-{{ help | escape_md }}
+{{ cmd.help_md | escape_md }}
 {%- endif %}
 
 {%- set args = cmd.args | filter(attribute="hide", value=false) %}
 {%- set flags = cmd.flags | filter(attribute="hide", value=false) %}
 {%- set global_flags = flags | filter(attribute="global", value=true) %}
 {%- set local_flags = flags | filter(attribute="global", value=false) %}
+{#- if no subcommands, don't display flags as global #}
+{%- if not cmd.subcommands %}
+{%- set local_flags = flags %}
+{%- set global_flags = [] %}
+{%- endif %}
 
 {%- if args %}
 
@@ -74,7 +76,7 @@
 {%- endfor -%}
 {%- endif -%}
 
-{%- if after_help %}
+{%- if cmd.after_help_md %}
 
-{{ after_help | escape_md }}
+{{ cmd.after_help_md | escape_md }}
 {%- endif -%}
diff --git a/lib/src/docs/markdown/templates/flag_template.md.tera b/lib/src/docs/markdown/templates/flag_template.md.tera
index 6e45420f..71b991d9 100644
--- a/lib/src/docs/markdown/templates/flag_template.md.tera
+++ b/lib/src/docs/markdown/templates/flag_template.md.tera
@@ -1,7 +1,6 @@
-{%- if flag.help_long_md %}{% set help = flag.long_help %}{% elif flag.help_long %}{% set help = flag.help_long %}{% elif flag.help %}{% set help = flag.help %}{% endif %}
-{%- if help %}
+{%- if flag.help_md %}
 
-{{ help | escape_md }}
+{{ flag.help_md | escape_md }}
 {%- endif %}
 {%- if flag.arg.choices %}
 
diff --git a/lib/src/docs/mod.rs b/lib/src/docs/mod.rs
index 558f17aa..7f829b58 100644
--- a/lib/src/docs/mod.rs
+++ b/lib/src/docs/mod.rs
@@ -1,2 +1,3 @@
 pub mod cli;
 pub mod markdown;
+mod models;
diff --git a/lib/src/docs/models.rs b/lib/src/docs/models.rs
new file mode 100644
index 00000000..06716b64
--- /dev/null
+++ b/lib/src/docs/models.rs
@@ -0,0 +1,313 @@
+use crate::docs::markdown::MarkdownRenderer;
+use crate::SpecChoices;
+use indexmap::IndexMap;
+use serde::Serialize;
+
+#[derive(Debug, Clone, serde::Serialize)]
+pub struct Spec {
+    pub name: String,
+    pub bin: String,
+    pub cmd: SpecCommand,
+    // pub config: SpecConfig,
+    pub version: Option<String>,
+    pub usage: String,
+    // pub complete: IndexMap<String, SpecComplete>,
+    pub source_code_link_template: Option<String>,
+    pub author: Option<String>,
+    pub about: Option<String>,
+    pub about_long: Option<String>,
+    pub about_md: Option<String>,
+    pub disable_help: Option<bool>,
+    pub min_usage_version: Option<String>,
+    pub rendered: bool,
+}
+
+#[derive(Debug, Serialize, Clone)]
+pub struct SpecCommand {
+    pub full_cmd: Vec<String>,
+    pub usage: String,
+    pub subcommands: IndexMap<String, SpecCommand>,
+    pub args: Vec<SpecArg>,
+    pub flags: Vec<SpecFlag>,
+    // pub mounts: Vec<SpecMount>,
+    pub deprecated: Option<String>,
+    pub hide: bool,
+    pub subcommand_required: bool,
+    pub help: Option<String>,
+    pub help_long: Option<String>,
+    pub help_md: Option<String>,
+    pub name: String,
+    pub aliases: Vec<String>,
+    pub hidden_aliases: Vec<String>,
+    pub before_help: Option<String>,
+    pub before_help_long: Option<String>,
+    pub before_help_md: Option<String>,
+    pub after_help: Option<String>,
+    pub after_help_long: Option<String>,
+    pub after_help_md: Option<String>,
+    pub examples: Vec<SpecExample>,
+    // pub complete: IndexMap<String, SpecComplete>,
+    pub rendered: bool,
+}
+
+#[derive(Debug, Default, Clone, Serialize)]
+pub struct SpecFlag {
+    pub name: String,
+    pub usage: String,
+    pub help: Option<String>,
+    pub help_long: Option<String>,
+    pub help_md: Option<String>,
+    pub help_first_line: Option<String>,
+    pub short: Vec<char>,
+    pub long: Vec<String>,
+    pub required: bool,
+    pub deprecated: Option<String>,
+    pub var: bool,
+    pub hide: bool,
+    pub global: bool,
+    pub count: bool,
+    pub arg: Option<SpecArg>,
+    pub default: Option<String>,
+    pub negate: Option<String>,
+    pub rendered: bool,
+}
+
+#[derive(Debug, Default, Serialize, Clone)]
+pub struct SpecExample {
+    pub code: String,
+    pub header: Option<String>,
+    pub help: Option<String>,
+    pub lang: String,
+    pub rendered: bool,
+}
+
+#[derive(Debug, Default, Clone, Serialize)]
+pub struct SpecArg {
+    pub name: String,
+    pub usage: String,
+    pub help: Option<String>,
+    pub help_long: Option<String>,
+    pub help_md: Option<String>,
+    pub help_first_line: Option<String>,
+    pub required: bool,
+    pub var: bool,
+    pub var_min: Option<usize>,
+    pub var_max: Option<usize>,
+    pub hide: bool,
+    pub default: Option<String>,
+    pub choices: Option<SpecChoices>,
+    pub rendered: bool,
+}
+
+impl From<crate::Spec> for Spec {
+    fn from(spec: crate::Spec) -> Self {
+        Self {
+            name: spec.name,
+            bin: spec.bin,
+            cmd: SpecCommand::from(&spec.cmd),
+            // config: SpecConfig::from(&spec.config),
+            version: spec.version,
+            usage: spec.usage,
+            // complete: spec.complete,
+            source_code_link_template: spec.source_code_link_template,
+            about: spec.about,
+            about_long: spec.about_long,
+            about_md: spec.about_md,
+            author: spec.author,
+            disable_help: spec.disable_help,
+            min_usage_version: spec.min_usage_version,
+            rendered: false,
+        }
+    }
+}
+
+impl From<&crate::SpecCommand> for SpecCommand {
+    fn from(cmd: &crate::SpecCommand) -> Self {
+        Self {
+            full_cmd: cmd.full_cmd.clone(),
+            usage: cmd.usage.clone(),
+            subcommands: cmd
+                .subcommands
+                .iter()
+                .map(|(k, v)| (k.clone(), SpecCommand::from(v)))
+                .collect(),
+            args: cmd.args.iter().map(SpecArg::from).collect(),
+            flags: cmd.flags.iter().map(SpecFlag::from).collect(),
+            // mounts: cmd.mounts.iter().map(SpecMount::from).collect(),
+            deprecated: cmd.deprecated.clone(),
+            hide: cmd.hide,
+            subcommand_required: cmd.subcommand_required,
+            help: cmd.help.clone(),
+            help_long: cmd.help_long.clone(),
+            help_md: cmd.help_md.clone(),
+            name: cmd.name.clone(),
+            aliases: cmd.aliases.clone(),
+            hidden_aliases: cmd.hidden_aliases.clone(),
+            before_help: cmd.before_help.clone(),
+            before_help_long: cmd.before_help_long.clone(),
+            before_help_md: cmd.before_help_md.clone(),
+            after_help: cmd.after_help.clone(),
+            after_help_long: cmd.after_help_long.clone(),
+            after_help_md: cmd.after_help_md.clone(),
+            examples: cmd.examples.iter().map(SpecExample::from).collect(),
+            // complete: cmd.complete.clone(),
+            rendered: false,
+        }
+    }
+}
+
+impl From<&crate::SpecFlag> for SpecFlag {
+    fn from(flag: &crate::SpecFlag) -> Self {
+        Self {
+            name: flag.name.clone(),
+            usage: flag.usage.clone(),
+            help: flag.help.clone(),
+            help_long: flag.help_long.clone(),
+            help_md: flag.help_md.clone(),
+            help_first_line: flag.help_first_line.clone(),
+            short: flag.short.clone(),
+            long: flag.long.clone(),
+            required: flag.required,
+            deprecated: flag.deprecated.clone(),
+            var: flag.var,
+            hide: flag.hide,
+            global: flag.global,
+            count: flag.count,
+            arg: flag.arg.as_ref().map(SpecArg::from),
+            default: flag.default.clone(),
+            negate: flag.negate.clone(),
+            rendered: false,
+        }
+    }
+}
+
+impl From<&crate::spec::cmd::SpecExample> for SpecExample {
+    fn from(example: &crate::spec::cmd::SpecExample) -> Self {
+        Self {
+            code: example.code.clone(),
+            header: example.header.clone(),
+            help: example.help.clone(),
+            lang: example.lang.clone(),
+            rendered: false,
+        }
+    }
+}
+
+impl From<&crate::SpecArg> for SpecArg {
+    fn from(arg: &crate::SpecArg) -> Self {
+        Self {
+            name: arg.name.clone(),
+            usage: arg.usage.clone(),
+            help: arg.help.clone(),
+            help_long: arg.help_long.clone(),
+            help_md: arg.help_md.clone(),
+            help_first_line: arg.help_first_line.clone(),
+            required: arg.required,
+            var: arg.var,
+            var_min: arg.var_min,
+            var_max: arg.var_max,
+            hide: arg.hide,
+            default: arg.default.clone(),
+            choices: arg.choices.clone(),
+            rendered: false,
+        }
+    }
+}
+
+impl Spec {
+    pub fn render_md(&mut self, renderer: &MarkdownRenderer) {
+        if self.rendered {
+            return;
+        }
+        self.rendered = true;
+        if let Some(h) = &mut self.about_md {
+            *h = renderer.replace_code_fences(h.to_string());
+        }
+        self.cmd.render_md(renderer);
+    }
+}
+
+impl SpecCommand {
+    pub fn all_subcommands(&self) -> Vec<&SpecCommand> {
+        let mut cmds = vec![];
+        for cmd in self.subcommands.values() {
+            cmds.push(cmd);
+            cmds.extend(cmd.all_subcommands());
+        }
+        cmds
+    }
+
+    pub fn render_md(&mut self, renderer: &MarkdownRenderer) {
+        if self.rendered {
+            return;
+        }
+        self.rendered = true;
+        if self.before_help_md.is_none() {
+            if let Some(h) = self.before_help_long.clone().or(self.before_help.clone()) {
+                self.before_help_md = Some(renderer.replace_code_fences(h));
+            }
+        }
+        if self.help_md.is_none() {
+            if let Some(h) = self.help_long.clone().or(self.help.clone()) {
+                self.help_md = Some(renderer.replace_code_fences(h));
+            }
+        }
+        if self.after_help_md.is_none() {
+            if let Some(h) = self.after_help_long.clone().or(self.after_help.clone()) {
+                self.after_help_md = Some(renderer.replace_code_fences(h));
+            }
+        }
+        for flag in &mut self.flags {
+            flag.render_md(renderer);
+        }
+        for arg in &mut self.args {
+            arg.render_md(renderer);
+        }
+        for example in &mut self.examples {
+            example.render_md(renderer);
+        }
+        for cmd in self.subcommands.values_mut() {
+            cmd.render_md(renderer);
+        }
+    }
+}
+
+impl SpecFlag {
+    pub fn render_md(&mut self, renderer: &MarkdownRenderer) {
+        if self.rendered {
+            return;
+        }
+        self.rendered = true;
+        if self.help_md.is_none() {
+            if let Some(h) = self.help_long.clone().or(self.help.clone()) {
+                self.help_md = Some(renderer.replace_code_fences(h));
+            }
+        }
+    }
+}
+
+impl SpecArg {
+    pub fn render_md(&mut self, renderer: &MarkdownRenderer) {
+        if self.rendered {
+            return;
+        }
+        self.rendered = true;
+        if self.help_md.is_none() {
+            if let Some(h) = self.help_long.clone().or(self.help.clone()) {
+                self.help_md = Some(renderer.replace_code_fences(h));
+            }
+        }
+    }
+}
+
+impl SpecExample {
+    pub fn render_md(&mut self, renderer: &MarkdownRenderer) {
+        if self.rendered {
+            return;
+        }
+        self.rendered = true;
+        if let Some(h) = self.help.clone() {
+            self.help = Some(renderer.replace_code_fences(h));
+        }
+    }
+}
diff --git a/lib/src/lib.rs b/lib/src/lib.rs
index a90a2039..92bf7491 100644
--- a/lib/src/lib.rs
+++ b/lib/src/lib.rs
@@ -15,6 +15,7 @@ pub use crate::spec::Spec;
 pub mod error;
 pub mod complete;
 pub mod spec;
+pub use error::Result;
 
 #[cfg(feature = "docs")]
 pub mod docs;
diff --git a/lib/src/test.rs b/lib/src/test.rs
index d8e9e5b1..d1dd18f8 100644
--- a/lib/src/test.rs
+++ b/lib/src/test.rs
@@ -9,7 +9,7 @@ macro_rules! spec {
 }
 
 pub static SPEC_KITCHEN_SINK: Lazy<Spec> = Lazy::new(|| {
-    spec! {r#"
+    spec! {r##"
 bin "mycli"
 source_code_link_template "https://github.com/jdx/mise/blob/main/src/cli/{{path}}.rs"
 arg "arg1" help="arg1 description"
@@ -21,7 +21,20 @@ arg "argrest" var=true
 arg "with-default" default="default value"
 
 flag "--flag1" help="flag1 description"
-flag "--flag2" help="flag2 description" long_help="flag2 long description"
+flag "--flag2" help="flag2 description" long_help=r#"flag2 long description
+
+includes a code block:
+
+    $ echo hello world
+    hello world
+    
+    more code
+
+some docs
+
+    $ echo hello world
+    hello world
+"#
 flag "--flag3" help="flag3 description" negate="--no-flag3"
 flag "--with-default" required=true default="default value"
 
@@ -30,17 +43,17 @@ flag "--shell <shell>" {
 }
 
 cmd "plugin" {
-  cmd "install" {
+  cmd "install" long_help="install a plugin" {
     arg "plugin"
     arg "version"
-    flag "-g --global"
+    flag "-g --global" global=true
     flag "-d --dir <dir>"
     flag "-f --force" negate="--no-force"
   }
 }
 
 complete "plugin" run="echo \"plugin-1\nplugin-2\nplugin-3\""
-"#}
+"##}
     .unwrap()
 });
 
diff --git a/mise.toml b/mise.toml
index fadc351e..7e8002a7 100644
--- a/mise.toml
+++ b/mise.toml
@@ -85,7 +85,7 @@ run = [
     'usage --usage-spec > cli/usage.usage.kdl',
     'rm -rf docs/cli/reference && mkdir -p docs/cli/reference',
     'usage g json -f cli/usage.usage.kdl > docs/cli/reference/commands.json',
-    'usage g md -mf cli/usage.usage.kdl --out-dir docs/cli/reference --url-prefix /cli/reference',
+    'usage g md -mf cli/usage.usage.kdl --out-dir docs/cli/reference --url-prefix /cli/reference --replace-pre-with-code-fences',
     'usage g completion bash usage --usage-cmd "usage --usage-spec" > cli/assets/completions/usage.bash',
     'usage g completion fish usage --usage-cmd "usage --usage-spec" > cli/assets/completions/usage.fish',
     'usage g completion zsh  usage --usage-cmd "usage --usage-spec" > cli/assets/completions/_usage',
@@ -95,8 +95,8 @@ run = [
 [tasks."render:example-md"]
 depends = ['build']
 run = [
-    "usage g md -f examples/mise.usage.kdl --out-file examples/docs/MISE_INLINE.md",
-    "usage g md -f examples/mise.usage.kdl --out-file examples/docs/MISE_MULTI.md",
+    "usage g md -f examples/mise.usage.kdl --out-file examples/docs/MISE_INLINE.md --replace-pre-with-code-fences",
+    "usage g md -f examples/mise.usage.kdl --out-file examples/docs/MISE_MULTI.md --replace-pre-with-code-fences",
 ]
 
 [tasks.release]