README Table of Contents

[dan.rossiter]

As WordPress plugins grow in complexity, the need for more sophisticated documentation also increases. A TOC tag, implemented on a per-page basis, would allow for this more sophisticated documentation.

The proposed syntax would be either <!-- TOC --> or {{TOC}}. Ideally, the tag would take attribute(s) allowing the user to specify how many levels of headers to be included, though this would not be entirely necessary.

[SergeyBiryukov]

Related: #156

[Otto42]

The current implementation of the readme.txt files does not support readme files much larger than about 10k to begin with, and even that causes major problems since the content of the readme.txt is sent as part of the API response.

Therefore, I would recommend NOT using the readme.txt for extensive documentation to begin with. Large changelogs should be moved out into separate files. FAQ sections should be limited to question for users *prior* to them installing your plugin.

Documentation on using the plugin should be contained within the plugin itself, possibly using the Help tabs built into WordPress or some other kind of explanatory screens in the admin. The readme.txt is not really the end-all be all of documentation.

As such, wontfix for now. Even in the future, when the readme.txt size limitation is removed, it will still be sent along in the API response, and so an arbitrary size limitation will likely be implemented. Probably about 8k or less.