Table of contents

Michel Fortin michel.fortin at
Fri Mar 6 06:17:39 EST 2009

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.

Michel Fortin
michel.fortin at

More information about the Markdown-Discuss mailing list