Skip to content

Navigation Menu

Sign in
Sign up

Support explicit root overview metadata in OpenCLI exports #80

Unanswered
JKamsker asked this question in Ideas and suggestions
Discussion options

Problem

When rendering docs from an OpenCLI export, the root overview page has very little app-level context unless the exporter provides it explicitly.

For example, for a CLI like Jellyfin-Cli, the ideal overview starts with something like:

Manage your Jellyfin server from the command line.

and then shows the top-level command areas.

Right now, the export mainly gives command structure, descriptions, options, and examples, but not a real root/app overview. That forces downstream renderers to invent fallback text from the command tree.

Why this matters

The root page is the first thing users read. It should explain what the CLI is for before dropping into the command list.

Without explicit root-level metadata:

  • generated docs feel incomplete at the top level
  • renderers need heuristics to guess intent
  • different renderers will likely produce inconsistent overview text

Suggested capability

It would help if OpenCLI supported explicit app-level overview metadata in the exported document, for example:

  • root summary
  • root description
  • optionally root examples or introductory notes

Something along the lines of:

  • info.summary
  • info.description

or another equivalent root-level structure if that fits the spec better.

Example use case

For a Jellyfin CLI, a renderer could then show:

  • Summary: Manage your Jellyfin server from the command line.
  • Description: short explanation of auth, browsing, administration, raw endpoint access, etc.
  • Then the linked top-level command list

Current workaround

A renderer can synthesize fallback overview text from command names and descriptions, but that is only a heuristic. It is useful as a fallback, not as the primary source of truth.

Request

Would you consider adding explicit root/app overview metadata to the OpenCLI model/export so generated documentation can produce a proper overview page without guessing?

You must be logged in to vote

Replies: 0 comments

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
1 participant

AltStyle によって変換されたページ (->オリジナル) /