# jonsequitur/system-commandline-extensions architecture

> Architecture diagram of the GitHub repository jonsequitur/system-commandline-extensions, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jonsequitur/system-commandline-extensions
- Repository: https://github.com/jonsequitur/system-commandline-extensions

## Overview

This repository provides two CLI-help packages: HelpLine.Docs lets an application expose Markdown documentation as discoverable topics, while HelpLine.HelpBuilder supplies a source-compatible System.CommandLine help renderer. The main Docs workflow loads or parses Markdown, maps headings into a topic catalog, and serves a list or selected/all topic content through a CLI command and Markdown renderer. The help-builder package separately formats command metadata into customizable help output. README confirms package capabilities; several implementation files were not sampled, so their internal wiring is represented only where documented or directly supported.

Main entry points: [`src/HelpLine.HelpBuilder/System.CommandLine.Help/HelpBuilder.cs`](https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.HelpBuilder/System.CommandLine.Help/HelpBuilder.cs) (Help formatter), [`src/HelpLine.Docs/DocsCommand.cs`](https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.Docs/DocsCommand.cs) (Docs command), [`src/HelpLine.Docs/MarkdownHelpRenderer.cs`](https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.Docs/MarkdownHelpRenderer.cs) (Markdown renderer), [`src/HelpLine.Docs/DocsTopicCatalog.cs`](https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.Docs/DocsTopicCatalog.cs) (Topic catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_docs["Markdown Docs"]
  node_catalog["Topic catalog"]
  node_heading_map["Heading mapping<br/>[HeadingContext.cs]"]
  node_topic["Topic metadata<br/>[DocsTopic.cs]"]
  node_docs_cmd["Docs command<br/>[DocsCommand.cs]"]
  node_topic_option["Topic option<br/>[DocsTopicOption.cs]"]
  node_list_cmd["List topics"]
  node_renderer["Markdown renderer"]
  node_visitor_interface["Markdown visitor"]
  node_plain_visitor["Plain text output"]
  node_spectre_visitor["Spectre output"]
end

subgraph group_builder["Help Builder"]
  node_help_action["Help action"]
  node_help_builder["Help formatter<br/>[HelpBuilder.cs]"]
  node_help_context["Help context<br/>[HelpContext.cs]"]
  node_default_layout["Default layout"]
  node_help_rows["Help rows"]
  node_extensions["Command extensions"]
  node_root_extensions["Root extensions"]
  node_localization["Localized labels"]
end

node_cli_user(("CLI user"))
node_cli_app["Host CLI app"]
node_markdown["Markdown docs"]
node_console["Terminal output"]

node_cli_user -->|"invokes"| node_cli_app
node_cli_app -->|"registers command"| node_docs_cmd
node_markdown -->|"loads/parses"| node_catalog
node_catalog -->|"maps headings"| node_heading_map
node_catalog -->|"creates entries"| node_topic
node_cli_user -->|"requests docs"| node_docs_cmd
node_docs_cmd -->|"reads selection"| node_topic_option
node_docs_cmd -->|"queries topics"| node_catalog
node_docs_cmd -->|"lists topics"| node_list_cmd
node_docs_cmd -->|"renders content"| node_renderer
node_renderer -->|"dispatches visits"| node_visitor_interface
node_renderer -->|"uses output visitor"| node_plain_visitor
node_renderer -->|"uses output visitor"| node_spectre_visitor
node_plain_visitor -->|"writes text"| node_console
node_spectre_visitor -->|"writes markup"| node_console
node_cli_user -->|"requests help"| node_help_action
node_help_action -->|"invokes formatting"| node_help_builder
node_help_builder -->|"uses operation context"| node_help_context
node_help_builder -->|"gets default sections"| node_default_layout
node_help_builder -->|"formats rows"| node_help_rows
node_default_layout -->|"builds sections"| node_help_rows
node_default_layout -->|"gets labels"| node_localization
node_help_builder -->|"writes help"| node_console
node_extensions -->|"configures help"| node_help_builder
node_root_extensions -->|"configures root help"| node_help_builder

click node_catalog "https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.Docs/DocsTopicCatalog.cs"
click node_heading_map "https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.Docs/HeadingContext.cs"
click node_topic "https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.Docs/DocsTopic.cs"
click node_docs_cmd "https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.Docs/DocsCommand.cs"
click node_topic_option "https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.Docs/DocsTopicOption.cs"
click node_list_cmd "https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.Docs/ListDocsTopicsCommand.cs"
click node_renderer "https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.Docs/MarkdownHelpRenderer.cs"
click node_visitor_interface "https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.Docs/IMarkdownVisitor.cs"
click node_plain_visitor "https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.Docs/PlainTextMarkdownVisitor.cs"
click node_spectre_visitor "https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.Docs/SpectreMarkdownVisitor.cs"
click node_help_action "https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.HelpBuilder/System.CommandLine.Help/CustomHelpAction.cs"
click node_help_builder "https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.HelpBuilder/System.CommandLine.Help/HelpBuilder.cs"
click node_help_context "https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.HelpBuilder/System.CommandLine.Help/HelpContext.cs"
click node_default_layout "https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.HelpBuilder/System.CommandLine.Help/HelpBuilder.Default.cs"
click node_help_rows "https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.HelpBuilder/System.CommandLine.Help/TwoColumnHelpRow.cs"
click node_extensions "https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.HelpBuilder/System.CommandLine.Help/HelpBuilderCommandExtensions.cs"
click node_root_extensions "https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.HelpBuilder/System.CommandLine.Help/RootCommandExtensions.cs"
click node_localization "https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.HelpBuilder/System.CommandLine.Help/LocalizationResources.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_catalog,node_heading_map,node_topic,node_docs_cmd,node_topic_option,node_list_cmd,node_renderer,node_visitor_interface,node_plain_visitor,node_spectre_visitor,node_cli_user toneBlue
class node_help_action,node_help_builder,node_help_context,node_default_layout,node_help_rows,node_extensions,node_root_extensions,node_localization toneAmber
class node_cli_app,node_markdown,node_console toneIndigo
```

## Components

### Markdown Docs

- [Topic catalog](https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.Docs/DocsTopicCatalog.cs): `src/HelpLine.Docs/DocsTopicCatalog.cs`
- [Heading mapping](https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.Docs/HeadingContext.cs): `src/HelpLine.Docs/HeadingContext.cs`
- [Topic metadata](https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.Docs/DocsTopic.cs): `src/HelpLine.Docs/DocsTopic.cs`
- [Docs command](https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.Docs/DocsCommand.cs): `src/HelpLine.Docs/DocsCommand.cs`
- [Topic option](https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.Docs/DocsTopicOption.cs): `src/HelpLine.Docs/DocsTopicOption.cs`
- [List topics](https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.Docs/ListDocsTopicsCommand.cs): `src/HelpLine.Docs/ListDocsTopicsCommand.cs`
- [Markdown renderer](https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.Docs/MarkdownHelpRenderer.cs): `src/HelpLine.Docs/MarkdownHelpRenderer.cs`
- [Markdown visitor](https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.Docs/IMarkdownVisitor.cs): `src/HelpLine.Docs/IMarkdownVisitor.cs`
- [Plain text output](https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.Docs/PlainTextMarkdownVisitor.cs): `src/HelpLine.Docs/PlainTextMarkdownVisitor.cs`
- [Spectre output](https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.Docs/SpectreMarkdownVisitor.cs): `src/HelpLine.Docs/SpectreMarkdownVisitor.cs`

### Help Builder

- [Help action](https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.HelpBuilder/System.CommandLine.Help/CustomHelpAction.cs): `src/HelpLine.HelpBuilder/System.CommandLine.Help/CustomHelpAction.cs`
- [Help formatter](https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.HelpBuilder/System.CommandLine.Help/HelpBuilder.cs): `src/HelpLine.HelpBuilder/System.CommandLine.Help/HelpBuilder.cs`
- [Help context](https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.HelpBuilder/System.CommandLine.Help/HelpContext.cs): `src/HelpLine.HelpBuilder/System.CommandLine.Help/HelpContext.cs`
- [Default layout](https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.HelpBuilder/System.CommandLine.Help/HelpBuilder.Default.cs): `src/HelpLine.HelpBuilder/System.CommandLine.Help/HelpBuilder.Default.cs`
- [Help rows](https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.HelpBuilder/System.CommandLine.Help/TwoColumnHelpRow.cs): `src/HelpLine.HelpBuilder/System.CommandLine.Help/TwoColumnHelpRow.cs`
- [Command extensions](https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.HelpBuilder/System.CommandLine.Help/HelpBuilderCommandExtensions.cs): `src/HelpLine.HelpBuilder/System.CommandLine.Help/HelpBuilderCommandExtensions.cs`
- [Root extensions](https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.HelpBuilder/System.CommandLine.Help/RootCommandExtensions.cs): `src/HelpLine.HelpBuilder/System.CommandLine.Help/RootCommandExtensions.cs`
- [Localized labels](https://github.com/jonsequitur/system-commandline-extensions/blob/main/src/HelpLine.HelpBuilder/System.CommandLine.Help/LocalizationResources.cs): `src/HelpLine.HelpBuilder/System.CommandLine.Help/LocalizationResources.cs`

### Other components

- **CLI user**
- **Host CLI app**
- **Markdown docs**
- **Terminal output**

## Connections

- CLI user → Host CLI app: invokes
- Host CLI app → Docs command: registers command
- Markdown docs → Topic catalog: loads/parses
- Topic catalog → Heading mapping: maps headings
- Topic catalog → Topic metadata: creates entries
- CLI user → Docs command: requests docs
- Docs command → Topic option: reads selection
- Docs command → Topic catalog: queries topics
- Docs command → List topics: lists topics
- Docs command → Markdown renderer: renders content
- Markdown renderer → Markdown visitor: dispatches visits
- Markdown renderer → Plain text output: uses output visitor
- Markdown renderer → Spectre output: uses output visitor
- Plain text output → Terminal output: writes text
- Spectre output → Terminal output: writes markup
- CLI user → Help action: requests help
- Help action → Help formatter: invokes formatting
- Help formatter → Help context: uses operation context
- Help formatter → Default layout: gets default sections
- Help formatter → Help rows: formats rows
- Default layout → Help rows: builds sections
- Default layout → Localized labels: gets labels
- Help formatter → Terminal output: writes help
- Command extensions → Help formatter: configures help
- Root extensions → Help formatter: configures root help