HelpLine.Docs 0.1.0-preview.37

HelpLine.Docs

Provide rich documentation directly in your CLI app.

1. Add Markdown files to your source project

Create a Docs\ folder in your project and add one or more Markdown files:

MyCli/
  Docs/
    getting-started.md
    advanced-usage.md

2. Build-time embedding

When your project references the HelpLine.Docs package, its transitive MSBuild targets automatically embed all *.md files under Docs\ as assembly resources. No .csproj changes are needed for the default setup.

To use a different source folder, set the MSBuild property:

<PropertyGroup>
  <HelpLineMarkdownTopicsRoot>MyCustomFolder</HelpLineMarkdownTopicsRoot>
</PropertyGroup>

3. Register the docs command

using HelpLine.Docs;
using System.CommandLine;

var catalog = DocsTopicCatalog.FromAssemblyResources(typeof(Program).Assembly);

var rootCommand = new RootCommand("sample");
rootCommand.Add(new DocsCommand(catalog));

This discovers embedded Markdown topics from the specified assembly and adds a docs subcommand. Every Markdown heading becomes a topic. Sub-topics are nested under their enclosing heading and shown indented in the interactive topic chooser:

> all topics
  boats
    engines
    rudders
  cars
    engines
    wheels

Topic content for a parent topic includes all of its descendant sections, so --topic boats displays the boats heading and content as well as everything below it (including engines and rudders).

When two topics share the same short name (e.g., an ## Engines topic under both # Cars and # Boats), each --topic value is qualified with its parent — cars-engines and boats-engines. The chooser still shows the unqualified engines under each parent.

4. Use at runtime

sample docs list
sample docs --topic boats

5. Advanced usage

For full control over how headings map to topics, pass a heading mapper:

var catalog = DocsTopicCatalog.FromAssemblyResources(typeof(Program).Assembly, context =>
{
    if (context.HeadingLevel == 2)
    {
        context.AppendToTopic(context.HeadingText);
    }
});

rootCommand.Add(new DocsCommand(catalog));

A mapped topic's content runs from its heading until the next mapped heading; unmapped headings are folded into the surrounding topic.