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, so 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.