Table of contents

[Michel Fortin]

Le 2009-03-05 à 4:27, Daniel Winterstein a écrit :


> I'm using Markdown in an app and would like to provide support for  

> including

> a table of contents.

> Any suggestions for a syntax? Has anyone done this before?

> My first thoughts are:

>

> 1. Have a special header item (using markdown extra's header  

> syntax), e.g.

>

> generate-contents: yes


Just to make things clear. PHP Markdown Extra doesn't have this kind  
of metadata syntax. Other implementations do however.



> 2. Have a special xml tag with optional alternative text inside, e.g.

>

> <contents>

> 1. First thingy

> 2. Second thingy

> 3. Other stuff

> </contents>


HTML and XML tags shouldn't be part of the Markdown syntax.



> 3. Detect that a set of list items matches the first few headers.  

> E.g. if

> the document has headers

>

> # Monkeys

> ## Chimps

> ## Humans

> ## Proboscis monkeys

> ## Other monkeys

> ## Do Lemur's count?

>

> Then a list that ran:

>

> 1. Monkeys

>   1. Chimps

>   2. Humans

>

> Would be detected as the start of a contents list, and the other  

> entries

> would automatically be added to it. This seems the nicest approach  

> in some

> respects, but also the one likely to cause confusion and annoyance.


I'd rather have a single tag, or another indicator saying "insert TOC  
here". Sample TOC content in your <contents> element is going fall out  
of sync with the rest of the document some day when you edit the  
document; I see no use for it.

That said, I believe the best way to generate a TOC is to implement  
HTML5's outline algorithm, working directly on the HTML or XHTML output.
<http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#outlines 
 >


-- 
Michel Fortin
michel.fortin at michelf.com
http://michelf.com/