Allow ReadMe to support in-document links for h4s

[MattyRob]

Migrated from ​#wp24295:

The current Plugin ​ReadMe files use MarkDown syntax and over time these can contain a great deal of information for users, for example in the FAQs.

The length of these sections sometimes makes finding the part you need a case of trawling through the entire document or searching for words in the browser window and hoping you are using the same vocabulary as the ReadMe author.

I think a useful enhancement would be to add the capability to define in-document links to allow for things like a table of contents at the top of the FAQ section. Currently you can create a link in such a table like this:

[FAQ 1](#1)

But I cannot find a way to create the linked section later in the document as any HTML, name or id parameters seem to get stripped out.

If this is already possible, please can you tell me how to accomplish this and accept my apologies from opening a ticket.

Note this is already possible for some levels (like h3s, which are wrapped in ==), but not in other levels (like h4s, which are wrapped in =).

[dan.rossiter]

What is the status on this? I develop a plugin with a massive amount of configurable content which I have judiciously documented, but the documentation would be significantly more usable with the ability to add a table of contents.

The MultiMarkdown (​http://fletcherpenney.net/multimarkdown/) syntax supports this functionality using [Header Name][], so maybe that's the best approach to stick with an existing standard.

If arbitrary header linking is not an option, maybe just allow for an optional auto-generated table of contents which would include all headers on the active tab.

[SergeyBiryukov]

Related: #1493

[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.

[MattyRob]

Replying to Otto42:

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.

I agree completely with the principles of this but there are a couple things that have been missed:

1. The current ​Readme example contains an FAQ header example - if it should not be in there then remove or amend that example.
2. The WordPress plugin repository is a fabulous place to put code for others to use and all for free - as that is the case a good number of plugin authors do not have the time or money to launch a website of their own to host FAQs - so where exactly then are FAQs (and likely other things) supposed to be hosted? It's all well and good saying where they should not go - but where then should they be? They really should be with the plugin file.

I'm not disagreeing with the sentiment that it needs to be done different or better but the WordPress plugin community deserves something a little better - the front end of the repository has not changed in almost 10 years - perhaps it should be revised as in need of a little polish.

[Otto42]

There's nothing wrong with the FAQ section in the readme, all I'm suggesting is that you make the info there most useful for people who have not installed your plugin yet. That information is displayed to users pre-install, not post-install.

See, once a plugin is installed, then the documentation can be made available right in the plugin itself. The Help tab dropdown is likely the best place for that. Have the information right there on the plugin settings page, basically. Why force users to go somewhere else to find the information they're looking for?

I initially wrote about the Help tabs back in 2011, and while the underlying code has changed a bit (for the better), the basic principles remain the same:
​http://ottopress.com/2011/new-in-wordpress-3-3-more-useful-help-screens/

[MattyRob]

We may well simply be disagreeing over semantics then - but it still needs making clearer IMO.

FAQs are 'Frequently Asked Questions', it seems to me that the ReadMe FAQs should be called 'Pre-install FAQs'. FAQs are usually used for common troubleshooting and support questions - the kind of things that don't crop up before installation.

As a final point - although you clearly know all about the Help tab - in my experience a large number of WordPress users are not aware it's even there. They ask on a forum rather than looking about on their own screen! :)

[Otto42]

Replying to MattyRob:

As a final point - although you clearly know all about the Help tab - in my experience a large number of WordPress users are not aware it's even there. They ask on a forum rather than looking about on their own screen! :)

You're not wrong, but most plugins don't use it very effectively either. If you have good docs in it, stick a pointer to it or something on the page so it gets noticed. :)