diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md
index 7e9ea67f2..0bec2fddb 100644
--- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md
+++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md
@@ -6,6 +6,8 @@
 color --fav=<fav> [--second=<second>] [--help]
 ```
 
+## Options
+
 - term **--fav=\<fav\>**:
 
 *Your favorite color.*
@@ -31,6 +33,8 @@ Show subcommand help information.
 color help [<subcommands>...]
 ```
 
+### Arguments
+
 - term **subcommands**:
 
 
diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md
index 6d16c6da3..bfa0ea34e 100644
--- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md
+++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md
@@ -6,6 +6,8 @@
 color --fav=<fav> [--second=<second>] [--help]
 ```
 
+## Options
+
 **--fav=\<fav\>:**
 
 *Your favorite color.*
@@ -31,6 +33,8 @@ Show subcommand help information.
 color help [<subcommands>...]
 ```
 
+### Arguments
+
 **subcommands:**
 
 
diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md
index 48d93d7cb..041af3559 100644
--- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md
+++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md
@@ -7,11 +7,15 @@ count-lines [<input-file>] [--prefix=<prefix>] [--verbose]
   [--help]
 ```
 
+## Arguments
+
 - term **input-file**:
 
 *A file to count lines in. If omitted, counts the lines of stdin.*
 
 
+## Options
+
 - term **--prefix=\<prefix\>**:
 
 *Only count lines with this prefix.*
@@ -35,8 +39,9 @@ Show subcommand help information.
 count-lines help [<subcommands>...]
 ```
 
-- term **subcommands**:
+### Arguments
 
+- term **subcommands**:
 
 
 
diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md
index 619e81d1c..1e3e6a183 100644
--- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md
+++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md
@@ -6,11 +6,15 @@
 count-lines [<input-file>] [--prefix=<prefix>] [--verbose] [--help]
 ```
 
+## Arguments
+
 **input-file:**
 
 *A file to count lines in. If omitted, counts the lines of stdin.*
 
 
+## Options
+
 **--prefix=\<prefix\>:**
 
 *Only count lines with this prefix.*
@@ -34,8 +38,9 @@ Show subcommand help information.
 count-lines help [<subcommands>...]
 ```
 
-**subcommands:**
+### Arguments
 
+**subcommands:**
 
 
 
diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md
index 847a76462..596cb13f7 100644
--- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md
+++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md
@@ -8,6 +8,8 @@ A utility for performing maths.
 math [--version] [--help]
 ```
 
+## Options
+
 - term **--version**:
 
 *Show the version.*
@@ -26,16 +28,20 @@ Print the sum of the values.
 math add [--hex-output] [<values>...] [--version] [--help]
 ```
 
-- term **--hex-output**:
-
-*Use hexadecimal notation for the result.*
-
+### Arguments
 
 - term **values**:
 
 *A group of integers to operate on.*
 
 
+### Options
+
+- term **--hex-output**:
+
+*Use hexadecimal notation for the result.*
+
+
 - term **--version**:
 
 *Show the version.*
@@ -57,16 +63,20 @@ math multiply [--hex-output] [<values>...] [--version]
   [--help]
 ```
 
-- term **--hex-output**:
-
-*Use hexadecimal notation for the result.*
-
+### Arguments
 
 - term **values**:
 
 *A group of integers to operate on.*
 
 
+### Options
+
+- term **--hex-output**:
+
+*Use hexadecimal notation for the result.*
+
+
 - term **--version**:
 
 *Show the version.*
@@ -87,6 +97,8 @@ Calculate descriptive statistics.
 math stats [--version] [--help]
 ```
 
+### Options
+
 - term **--version**:
 
 *Show the version.*
@@ -106,16 +118,20 @@ math stats average [--kind=<kind>] [<values>...] [--version]
   [--help]
 ```
 
-- term **--kind=\<kind\>**:
-
-*The kind of average to provide.*
-
+#### Arguments
 
 - term **values**:
 
 *A group of floating-point values to operate on.*
 
 
+#### Options
+
+- term **--kind=\<kind\>**:
+
+*The kind of average to provide.*
+
+
 - term **--version**:
 
 *Show the version.*
@@ -136,11 +152,15 @@ Print the standard deviation of the values.
 math stats stdev [<values>...] [--version] [--help]
 ```
 
+#### Arguments
+
 - term **values**:
 
 *A group of floating-point values to operate on.*
 
 
+#### Options
+
 - term **--version**:
 
 *Show the version.*
@@ -166,6 +186,8 @@ math stats quantiles [<one-of-four>] [<custom-arg>]
   [--help]
 ```
 
+#### Arguments
+
 - term **one-of-four**:
 
 
@@ -180,6 +202,8 @@ math stats quantiles [<one-of-four>] [<custom-arg>]
 *A group of floating-point values to operate on.*
 
 
+#### Options
+
 - term **--file=\<file\>**:
 
 
@@ -217,9 +241,13 @@ Show subcommand help information.
 math help [<subcommands>...] [--version]
 ```
 
+### Arguments
+
 - term **subcommands**:
 
 
+### Options
+
 - term **--version**:
 
 *Show the version.*
diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md
index 00997feb5..ccdc5dca7 100644
--- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md
+++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md
@@ -8,6 +8,8 @@ A utility for performing maths.
 math [--version] [--help]
 ```
 
+## Options
+
 **--version:**
 
 *Show the version.*
@@ -26,16 +28,20 @@ Print the sum of the values.
 math add [--hex-output] [<values>...] [--version] [--help]
 ```
 
-**--hex-output:**
-
-*Use hexadecimal notation for the result.*
-
+### Arguments
 
 **values:**
 
 *A group of integers to operate on.*
 
 
+### Options
+
+**--hex-output:**
+
+*Use hexadecimal notation for the result.*
+
+
 **--version:**
 
 *Show the version.*
@@ -56,16 +62,20 @@ Print the product of the values.
 math multiply [--hex-output] [<values>...] [--version] [--help]
 ```
 
-**--hex-output:**
-
-*Use hexadecimal notation for the result.*
-
+### Arguments
 
 **values:**
 
 *A group of integers to operate on.*
 
 
+### Options
+
+**--hex-output:**
+
+*Use hexadecimal notation for the result.*
+
+
 **--version:**
 
 *Show the version.*
@@ -86,6 +96,8 @@ Calculate descriptive statistics.
 math stats [--version] [--help]
 ```
 
+### Options
+
 **--version:**
 
 *Show the version.*
@@ -104,16 +116,20 @@ Print the average of the values.
 math stats average [--kind=<kind>] [<values>...] [--version] [--help]
 ```
 
-**--kind=\<kind\>:**
-
-*The kind of average to provide.*
-
+#### Arguments
 
 **values:**
 
 *A group of floating-point values to operate on.*
 
 
+#### Options
+
+**--kind=\<kind\>:**
+
+*The kind of average to provide.*
+
+
 **--version:**
 
 *Show the version.*
@@ -134,11 +150,15 @@ Print the standard deviation of the values.
 math stats stdev [<values>...] [--version] [--help]
 ```
 
+#### Arguments
+
 **values:**
 
 *A group of floating-point values to operate on.*
 
 
+#### Options
+
 **--version:**
 
 *Show the version.*
@@ -162,6 +182,8 @@ math stats quantiles [<one-of-four>] [<custom-arg>] [<custom-deprecated-arg>]
   [--help]
 ```
 
+#### Arguments
+
 **one-of-four:**
 
 
@@ -176,6 +198,8 @@ math stats quantiles [<one-of-four>] [<custom-arg>] [<custom-deprecated-arg>]
 *A group of floating-point values to operate on.*
 
 
+#### Options
+
 **--file=\<file\>:**
 
 
@@ -213,9 +237,13 @@ Show subcommand help information.
 math help [<subcommands>...] [--version]
 ```
 
+### Arguments
+
 **subcommands:**
 
 
+### Options
+
 **--version:**
 
 *Show the version.*
diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md
index 60f104d78..e69e1f2e4 100644
--- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md
+++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md
@@ -7,6 +7,15 @@ repeat [--count=<count>] [--include-counter] <phrase>
   [--help]
 ```
 
+## Arguments
+
+- term **phrase**:
+
+*The phrase to repeat.*
+
+
+## Options
+
 - term **--count=\<count\>**:
 
 *How many times to repeat 'phrase'.*
@@ -17,11 +26,6 @@ repeat [--count=<count>] [--include-counter] <phrase>
 *Include a counter with each repetition.*
 
 
-- term **phrase**:
-
-*The phrase to repeat.*
-
-
 - term **--help**:
 
 *Show help information.*
@@ -35,6 +39,8 @@ Show subcommand help information.
 repeat help [<subcommands>...]
 ```
 
+### Arguments
+
 - term **subcommands**:
 
 
diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md
index f3ab3e621..74724c97f 100644
--- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md
+++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md
@@ -6,6 +6,15 @@
 repeat [--count=<count>] [--include-counter] <phrase> [--help]
 ```
 
+## Arguments
+
+**phrase:**
+
+*The phrase to repeat.*
+
+
+## Options
+
 **--count=\<count\>:**
 
 *How many times to repeat 'phrase'.*
@@ -16,11 +25,6 @@ repeat [--count=<count>] [--include-counter] <phrase> [--help]
 *Include a counter with each repetition.*
 
 
-**phrase:**
-
-*The phrase to repeat.*
-
-
 **--help:**
 
 *Show help information.*
@@ -34,6 +38,8 @@ Show subcommand help information.
 repeat help [<subcommands>...]
 ```
 
+### Arguments
+
 **subcommands:**
 
 
diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md
index 306fae0d0..9973c7c2b 100644
--- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md
+++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md
@@ -7,6 +7,8 @@ roll [--times=<n>] [--sides=<m>] [--seed=<seed>] [--verbose]
   [--help]
 ```
 
+## Options
+
 - term **--times=\<n\>**:
 
 *Rolls the dice <n> times.*
@@ -42,6 +44,8 @@ Show subcommand help information.
 roll help [<subcommands>...]
 ```
 
+### Arguments
+
 - term **subcommands**:
 
 
diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md
index 8e0bd3874..0f4ad115d 100644
--- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md
+++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md
@@ -6,6 +6,8 @@
 roll [--times=<n>] [--sides=<m>] [--seed=<seed>] [--verbose] [--help]
 ```
 
+## Options
+
 **--times=\<n\>:**
 
 *Rolls the dice <n> times.*
@@ -41,6 +43,8 @@ Show subcommand help information.
 roll help [<subcommands>...]
 ```
 
+### Arguments
+
 **subcommands:**
 
 
diff --git a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift
index 722245fed..21cb38dbe 100644
--- a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift
+++ b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift
@@ -77,34 +77,67 @@ extension CommandInfoV0 {
       result += "\(discussion)\n\n"
     }
 
-    if let args = self.arguments {
-      for arg in args {
-        guard arg.shouldDisplay else {
-          continue
-        }
+    result += self.argumentListMarkdown(
+      path: path, markdownStyle: markdownStyle)
 
-        switch markdownStyle {
-        case .docc:
-          result += "- term **\(arg.identity())**:\n\n"
-        case .github:
-          result += "**\(arg.identity()):**\n\n"
-        }
+    for subcommand in self.subcommands ?? [] {
+      result +=
+        subcommand.toMarkdown(
+          path + [self.commandName], markdownStyle: markdownStyle) + "\n\n"
+    }
 
-        if let abstract = arg.abstract {
-          result += "*\(abstract)*\n\n"
-        }
-        if let discussion = arg.discussion {
-          result += discussion + "\n\n"
+    return result
+  }
+
+  /// Emits grouped argument documentation matching command-line help ordering:
+  /// Arguments, then custom section titles (definition order), then Options.
+  fileprivate func argumentListMarkdown(
+    path: [String],
+    markdownStyle: OutputStyle
+  ) -> String {
+    guard let args = self.arguments else {
+      return ""
+    }
+    let displayed = args.filter(\.shouldDisplay)
+    guard !displayed.isEmpty else {
+      return ""
+    }
+
+    var positional: [ArgumentInfoV0] = []
+    var titled: [String: [ArgumentInfoV0]] = [:]
+    var sectionOrder: [String] = []
+    var options: [ArgumentInfoV0] = []
+
+    for arg in displayed {
+      if let title = arg.sectionTitle, !title.isEmpty {
+        if !titled.keys.contains(title) {
+          sectionOrder.append(title)
         }
-        result += "\n"
+        titled[title, default: []].append(arg)
+      } else if arg.kind == .positional {
+        positional.append(arg)
+      } else {
+        options.append(arg)
       }
     }
 
-    for subcommand in self.subcommands ?? [] {
-      result +=
-        subcommand.toMarkdown(
-          path + [self.commandName], markdownStyle: markdownStyle) + "\n\n"
+    var result = ""
+    let headingLevel = path.count + 2
+    let headingPrefix = String(repeating: "#", count: headingLevel)
+
+    func appendSection(title: String, arguments: [ArgumentInfoV0]) {
+      guard !arguments.isEmpty else { return }
+      result += "\(headingPrefix) \(title)\n\n"
+      for arg in arguments {
+        result += arg.markdownTermBody(markdownStyle: markdownStyle)
+      }
+    }
+
+    appendSection(title: "Arguments", arguments: positional)
+    for title in sectionOrder {
+      appendSection(title: title, arguments: titled[title] ?? [])
     }
+    appendSection(title: "Options", arguments: options)
 
     return result
   }
@@ -209,4 +242,22 @@ extension ArgumentInfoV0 {
     }
     return inner
   }
+
+  fileprivate func markdownTermBody(markdownStyle: OutputStyle) -> String {
+    var result = ""
+    switch markdownStyle {
+    case .docc:
+      result += "- term **\(identity())**:\n\n"
+    case .github:
+      result += "**\(identity()):**\n\n"
+    }
+    if let abstract = self.abstract {
+      result += "*\(abstract)*\n\n"
+    }
+    if let discussion = self.discussion {
+      result += discussion + "\n\n"
+    }
+    result += "\n"
+    return result
+  }
 }