From f498fb4007b518e6710b0bd4d5d1295bdd845754 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Sun, 15 Sep 2024 11:16:29 -0700
Subject: [PATCH] Add docs

---
 CHANGELOG.md        |  3 ++-
 docs/advanced.md    |  5 +++--
 docs/documenting.md | 23 +++++++++++++++++++++--
 3 files changed, 26 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ec07c7b2..a88f1b5f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,7 @@
 - Added `associate{}`, `associateBy{}`, and `associateWith{}` transforms for options that allow you to convert the keys and values of the map.  ([#529](https://github.com/ajalt/clikt/pull/529))
 - Added support for aliasing options to other options. ([#535](https://github.com/ajalt/clikt/pull/535))
 - Added `limit` and `ignoreCase` parameters to `option().split()`. ([#541](https://github.com/ajalt/clikt/pull/541))
+- Support calling `--help` on subcommands when parents have required parameters.
 
 ### Changed
 - In a subcommand with and an `argument()` with `multiple()` or `optional()`, the behavior is now the same regardless of the value of `allowMultipleSubcommands`: if a token matches a subcommand name, it's now treated as a subcommand rather than a positional argument.
@@ -39,8 +40,8 @@
 - **Breaking Change:** `CliktCommand.main` and `CliktCommand.parse` are now extension functions rather than methods.
 - **Breaking Change:** `Context.obj` and `Context.terminal`, and `OptionTransformContext.terminal` are now extension functions rather than properties.
 - **Breaking Change:** The `RenderedSection` and `DefinitionRow` classes have moved to `AbstractHelpFormatter`.
+- Markdown support in the help formatter is no longer included by default. To enable it, include the `:clikt-markdown` dependency and call `yourCommand.installMordantMarkdown()` before parsing.
 - Updated Kotlin to 2.0.0
-- Support calling `--help` on subcommands when parents have required parameters.
 
 ### Fixed
 - Fixed excess arguments not being reported when `allowMultipleSubcommands=true` and a subcommand has excess arguments followed by another subcommand.
diff --git a/docs/advanced.md b/docs/advanced.md
index 77df2e5b..4df3777a 100644
--- a/docs/advanced.md
+++ b/docs/advanced.md
@@ -565,7 +565,7 @@ dependencies {
 ```
 
 The [CliktCommand] class is only available in the full module, so you'll need to use
-[CoreCliktCommand] instead. The `CoreCliktCommand` has the same API as `CliktCommand`, but it
+[CoreCliktCommand] (or [CoreNoOpCliktCommand]) instead. The `CoreCliktCommand` has the same API as `CliktCommand`, but it
 doesn't have any of these features built in:
 
 - Text wrapping, formatting, markdown, or color support
@@ -640,7 +640,8 @@ These platforms are supported for the [core module](#core-module) only.
 
 [BaseCliktCommand]:              api/clikt/com.github.ajalt.clikt.core/-base-clikt-command/index.html
 [CliktCommand]:                  api/clikt-mordant/com.github.ajalt.clikt.core/-clikt-command/index.html
-[CliktCommand]:                  api/clikt/com.github.ajalt.clikt.core/-core-clikt-command/index.html
+[CoreCliktCommand]:              api/clikt/com.github.ajalt.clikt.core/-core-clikt-command/index.html
+[CoreNoOpCliktCommand]:          api/clikt/com.github.ajalt.clikt.core/-core-no-op-clikt-command/index.html
 [CommandLineParser]:             api/clikt/com.github.ajalt.clikt.parsers/-command-line-parser/index.html
 [CommandLineParser.main]:        api/clikt/com.github.ajalt.clikt.parsers/-command-line-parser/main.html
 [CommandLineParser.parse]:       api/clikt/com.github.ajalt.clikt.parsers/-command-line-parser/parse.html
diff --git a/docs/documenting.md b/docs/documenting.md
index c0957072..2627d20c 100644
--- a/docs/documenting.md
+++ b/docs/documenting.md
@@ -67,12 +67,31 @@ describe arguments in the command help.
 
 ## Markdown in help texts
 
-All help texts use Mordant to render Markdown. You can use all the normal markdown features, such as
-lists, tables, and even hyperlinks if your terminal supports them.
+You can configure Clikt to use Mordant to render Markdown in help texts. You can use all the normal
+markdown features, such as lists, tables, and even hyperlinks if your terminal supports them.
+
+First, add the `:clitk-markdown` dependency to your project:
+
+```kotlin
+dependencies {
+   implementation("com.github.ajalt.clikt:clikt-markdown:$cliktVersion")
+}
+```
+
+And install the markdown help formatter on your command:
+
+```kotlin
+val command = MyCommand().installMordantMarkdown()
+```
+
+Then you can use markdown in your help strings:
 
 === "Example"
     ```kotlin
     class Tool : NoOpCliktCommand() {
+        init {
+            installMordantMarkdown()
+        }
         val option by option().help {
             """
             | This | is | a | table |