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 2. Have a special xml tag with optional alternative text inside, e.g. <contents> 1. First thingy 2. Second thingy 3. Other stuff </contents> 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. Your thoughts? - Daniel -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://six.pairlist.net/pipermail/markdown-discuss/attachments/20090305/c9a21b35/attachment.html>
On Thu, Mar 5, 2009 at 4:27 AM, Daniel Winterstein <daniel.winterstein at gmail.com> wrote:> > 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?Yes, Python-Markdown has an extension [1] that does this. Unfortunately, its not documented properly yet (it hasn't been officially released yet either), but it works on the same basic premise as your third suggestion. It uses all the headers to build a nested list and then either inserts that list at the location of the marker ``[TOC]``, or if the marker is not found, at the beginning of the document. [1]: http://gitorious.org/projects/python-markdown/repos/mainline/blobs/master/markdown/extensions/toc.py -- ---- \X/ /-\ `/ |_ /-\ |\| Waylan Limberg
In article <f0fff4860903050127k9095a5dtcedf15dd094f11cc at mail.gmail.com>, Daniel Winterstein <markdown-discuss at six.pairlist.net> wrote:>--===============0471983932=>Content-Type: multipart/alternative; boundary=001636c59672452e2f04645bc875 > >--001636c59672452e2f04645bc875 >Content-Type: text/plain; charset=ISO-8859-1 >Content-Transfer-Encoding: 7bit > >I'm using Markdown in an app and would like to provide support for including >a table of contents.A couple of the markdown implementations have got support for tables of contents. Discount (my implementation) supports it (it builds a table of contents from the headers and lets you get to it via a library call,) the python implementation has one, as does pandoc. -david parsons
i'm told that typophiles consider "table of contents" to be redundant, and that "contents" is sufficient... whatever... at any rate, of course you will want to make sure that the toc entries _link_ to their respective chapters, but don't stop there, my friends. have the chapter headers link _back_ to the contents page, to improve navigation. and sometimes people want to "skim across" chapters, so put a link on each chapter that goes to the next one. and another link that goes to the previous one as well... follow the same procedure for the table of illustrations. and figures. and any other structure that's appropriate. some of you will be inclined to dismiss this as overkill. fine. be that way. those of you who actually try it, and use it for a while, will come to learn that it's really quite handy, and you will continue using it forever, and be glad you tried it. -bowerbird ************** A Good Credit Score is 700 or Above. See yours in just 2 easy steps! (http://pr.atwola.com/promoclk/100126575x1219957551x1201325337/aol?redir=http:%2F%2Fwww.freecreditreport.com%2Fpm%2Fdefault.aspx%3Fsc%3D668072%26hmpgID %3D62%26bcd%3DfebemailfooterNO62) -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://six.pairlist.net/pipermail/markdown-discuss/attachments/20090305/62b05d37/attachment.html>
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: yesJust 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/