Introduce Featured Commands in README in scaffold package-readme

[ernilambar]

Feature Request

• [x] Yes, I reviewed the contribution guidelines.

Describe your use case and the problem you are facing

For package with large number of commands and subcommands, navigating through commands is quite difficult. TOC in the beginning of readme would be very helpful.

Describe the solution you'd like

List the commands anchored with corresponding command.

Example: https://github.com/ernilambar/entity-command/blob/toc/README.md

[danielbachhuber]

Thanks for the suggestion!

I think listing all of the commands in a TOC could be a bit much for some. However, we could allow package authors curate the most popular commands into TOC (and indicate as such).

[ernilambar]

In extra in composer.json, lets support featured-commands parameter:

    "featured-commands": [
      "database test",
      "database reset"
    ],

Output would be:

Example: https://github.com/ernilambar/database-command/tree/yo-toc#readme

[danielbachhuber]

Cool, I think that looks reasonably good.

[swissspidy]

FWIW, GitHub already shows a table of contents:

IIRC we already had this discussion at some point.

[ernilambar]

Yah it seems there is already an issue: https://github.com/wp-cli/scaffold-package-command/issues/141

[ernilambar]

@swissspidy That GitHub thingy of readme file looks cool. I didn't know that. Nice. This issue was started with full TOC is mind but now discussion is going around featured commands

[ernilambar]

@danielbachhuber Featured commands was sparked from the need to see all commands in a bird eye view, which GitHub kind of already provides (even though with one extra click). So I am now neutral about this now. I am ok whatever you decide.

[danielbachhuber]

Yeah, let's wontfix this. I think it's only a problem when a package has a lot of commands, which is just a few.

Package authors can easily highlight featured commands by creating a custom section part