Embed your documentation in the binary¶

Put the markdown where the loader looks¶

docs reads from the tool's rtb_assets::Assets overlay, under a root that defaults to docs:

assets/
  docs/
    intro.md
    guide/
      setup.md
      troubleshooting.md

Only *.md files are loaded. Anything else under the root is skipped, and there is no route or subcommand that serves it — an <img src="../diagram.png"> will 404 from docs serve. Reference images by absolute URL or leave them out.

Hand the assets to the builder¶

Application::builder()
    .metadata(metadata)
    .version(rtb_app::version_info!())
    .assets(assets)
    .build()?

Building the Assets overlay is rtb-assets's job. Without .assets(...) the overlay is empty and every docs subcommand fails with docs root not found in assets: docs.

Also make sure something in your binary references rtb_docs, or the command will not exist at all — see add a command.

Decide whether you need an `_index.yaml`¶

Without one, the navigation is synthesised: each page's first # Heading becomes its title, and pages are grouped by their top-level directory, with anything directly under the root landing in a section called Overview.

That is usually enough. Write <root>/_index.yaml when you want a specific order, different titles, or sections that do not match the directory layout:

title: My Tool Documentation
sections:
  - title: Getting started
    pages:
      - { path: intro.md, title: Introduction }
      - { path: guide/setup.md, title: Install and configure }
  - title: Reference
    pages:
      - { path: guide/troubleshooting.md, title: Troubleshooting }

path is relative to the root and includes the extension. A path containing .. or an absolute path is rejected at load time.

Every page you want found must be listed¶

Once _index.yaml exists it is the entire navigation. An unlisted page is still loaded — docs show renders it and the HTTP server serves it by path — but it does not appear in docs list, in the browser's index, or in any search result. Search is built from index entries, not from the file set.

That makes a forgotten entry silent. If a page seems to have vanished from search, check the index before checking the search code.

Verify each surface¶

$ mytool docs list
My Tool Documentation

# Getting started
  intro.md — Introduction
  guide/setup.md — Install and configure

$ mytool docs show intro.md
$ mytool docs serve
docs server listening on http://127.0.0.1:34177

docs serve binds to 127.0.0.1:0 by default — loopback, ephemeral port. That is a default, not a restriction: --bind 0.0.0.0:8080 exposes it on every interface, with no authentication and no TLS.

docs rejects --output in any position. Do not offer it to users.

docs reference — flags, routes, TUI key bindings, and what the browser cannot do.
rtb-docs — why documentation lives in the binary.