Improve visualisation of command hierarchy in headings
florimondmanca opened this issue · 0 comments
florimondmanca commented
Problem statement
Consider a nested CLI, ie one group with one or more nested commands or groups.
Right now the TOC looks like this:
- root
- subgroup1
- subcommand1
- subcommand2
- ...
- subcommand3
- ...
- subgroup1
This is nice and clean, as it allows visualizing the
But… In the page content itself, the hierarchy is only represented by heading styles (more or less big/bold text), like this:
root
Usage: ...
Options: ...
subgroup1
Usage: ...
Options:...
subcommand1
Usage: ...
Options: ...
subcommand2
Usage: ...
Options: ...
subcommand3
Usage: ...
Options: ...
When looking at a given section, it is not obvious to know whether a given command
belongs to a parent group (and which one) (see subcommand1
and subcommand2
), or if it's just a standalone command (see subcommand3
).
Besides, permalinks only contain eg /#subcommand2
, which again doesn't convey the actual hierarchy.
Suggested solution
- Make headings contain the full
command_path
, eg## root subgroup1 subcommand2
- Permalinks should be updated too, eg
/#root-subgroup1-subcommand2
(see custom labels) - TOC entries should not change, as the TOC already conveys the hierarchy just fine.