Provide table of contents in readme
schittli opened this issue · comments
Thank you very much for sharing your great work!
Feature Request
- Yes, I reviewed the contribution guidelines
Describe your use case and the problem you are facing
If one creates a pdf from README.md, then it creates 127 pages. A lot of work!
But this work get's pretty useless, because if someone does not know entity-command, then it's almost impossible to get a useful overview.
Describe the solution you'd like
Please, create a table of contents, at least with Header 1, so that users can jump to the interesting chapters like system requirements, setup and commands for comments, menus, options, posts, sites, terms, and users.
Thanks a lot, kind regards,
Thomas
Github already creates TOC based on headings - you can access it in by clicking on 3 bar icon top-left of main header containing name of the file.
If I recall correctly, wp scaffold package-readme offers some ability to inject additional content into the README.md
I agree that wp-cli/entity-command does a lot and can be quite overwhelming.
@schittli If we were to include a more helpful introductory paragraph at the beginning of README.md, what do you think that should be?
@schittli Please take a look at https://github.com/dsXLII/entity-command/tree/ds_384 (I added a simple TOC near the top of README.me) -- is that the sort of thing you had in mind?
(Since Daniel mentioned scaffolds and injecting content, I assume that "directly editing README.md" isn't the optimal way to do this; call it a proof of concept, and if it looks decent then I'll go try to figure out the "right" approach.)
(Since Daniel mentioned scaffolds and injecting content, I assume that "directly editing README.md" isn't the optimal way to do this; call it a proof of concept, and if it looks decent then I'll go try to figure out the "right" approach.)
@dsXLII Here's an overview to how README generation works: https://github.com/wp-cli/scaffold-package-command/#wp-scaffold-package-readme
I like the simple TOC you added. We could update wp scaffold package-readme to either auto-generate a TOC like that when a package has more than three top-level commands, or we could make using_toc_commands a supported composer.json value.
