[wp-hackers] Plugin readme #section links

[Michael D Adams]

On Fri, Jun 25, 2010 at 1:32 PM, Dan Phiffer <dan at phiffer.org> wrote:
> I have a rather big readme file for my JSON API plugin (http://wordpress.org/extend/plugins/json-api/other_notes/) and I'm concerned that it's getting a bit unwieldy in its current form. As far as I know there's not a way to create hash links (#foo) in plugin readme files. Markdown doesn't seem to provide a way to made id attributes (see: http://daringfireball.net/projects/markdown/syntax.text which resorts to <h2 id="section">...</h2>) and I'm not sure what a reasonable syntax might look like. But I thought I'd float the general idea here and see if anyone else might find this useful.

For your case, it looks like you only need to link to headings within
what the Plugins Directory displays as "Other Notes" (the URL you
linked: http://wordpress.org/extend/plugins/json-api/other_notes/ ).
Is that true or do you want to be able to link to arbitrary places
(not just headings)?

What if the plugins directory automatically generated id attributes
for the header elements (like MediaWiki does)?

So for your example:


See the [API Reference](#API Reference) section below for a complete
method listing.

== API Reference ==

The JSON API reference is split into four sections


Might turn into:


<p>See the <a href="#api-reference">API Reference</a> section below
for a complete method listing.</p>

<h3 id="api-reference">API Reference</h3>

<p>The JSON API reference is split into four sections:</p>


Or maybe even:


See the <#API Reference> section below for a complete method listing.