Re: Table of contents
Sherwood Botsford wrote:
> I *don't* think that markdown is the place for this however.
> I think this is better approached by your page generating software.
MojoMojo uses MultiMarkdown, and I wrote a TOC plugin for it. It uses
HTML::Toc to generate the tableof contents from the HTML that MMD
spits out. The syntax is:
{{toc M- }} # start from Header level M
{{toc -N }} # stop at Header level N
{{toc M-N }}# process only header levels M..N
where M is the minimum heading level to include in the TOC, and N is
the maximum level (depth). For example, suppose you only have one H1
on the page so it doesn't make sense to add it to the TOC; also,
assume you and don't want to include any headers smaller than H3. The
{{toc}} markup to achieve that would be:
{{toc 2-3}}
Dan
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: Table of contents
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. 1. First thingy 2. Second thingy 3. Other stuff 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 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.for...@michelf.com http://michelf.com/ ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: Table of contents
MultiMarkdown has the ability to generate such a ToC, complete with links from the headers back to the ToC via the xhtml-toc.xslt file. Strictly speaking, this file can be used by xsltproc on any XHTML file, not necessarily one that was created by MMD. Fletcher On Mar 5, 2009, at 1:03 PM, Sherwood Botsford wrote: The bird is right on this one. You want easy ways to navigate, and multiple ones to navigate. I *don't* think that markdown is the place for this however. I find working even with Markdown to put a picture in a file is slow and awkward. You want to avoid this level of detail while you are writing. You want to write, not tweak brackets and braces and such. Don't turn MD into the mess that HTML is. I think this is better approached by your page generating software. Consider: Write your basic markdown. Labelmaker goes through your markdown, and any header lines get an auto generated label put before them to create an anchor. Labelmaker is customized to look for sequences like ### Table and # Figure and do the right thing. The previous-toc-next links are handled by your templating software. Now you are just writing markdown. the only thing I'd add to markdown would be a good mechanism for resolving links externally, so that if you rename a file, you don't have to back trace all the files that reference them. Again this should be programmed. You put the link in normally the first time. A program pulls the links out, puts a 'external reference link' tag in markdown, and adds this to the external link. Ideally it's smart enough taht if you reference something several times, it reuses the tag. Now if you rename or move a file, you only have to fix it in the single external links file. -- Sherwood Botsford Sherwood's Forests Warburg, Alberta T0C 2T0 http://www.sherwoods-forests.com 780-848-2548 ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss -- Fletcher T. Penney fletc...@fletcherpenney.net People demand freedom of speech to make up for the freedom of thought which they avoid. - Soren Aabye Kierkegaard (1813-1855) smime.p7s Description: S/MIME cryptographic signature ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: Table of contents
The bird is right on this one. You want easy ways to navigate, and multiple ones to navigate. I *don't* think that markdown is the place for this however. I find working even with Markdown to put a picture in a file is slow and awkward. You want to avoid this level of detail while you are writing. You want to write, not tweak brackets and braces and such. Don't turn MD into the mess that HTML is. I think this is better approached by your page generating software. Consider: Write your basic markdown. Labelmaker goes through your markdown, and any header lines get an auto generated label put before them to create an anchor. Labelmaker is customized to look for sequences like ### Table and # Figure and do the right thing. The previous-toc-next links are handled by your templating software. Now you are just writing markdown. the only thing I'd add to markdown would be a good mechanism for resolving links externally, so that if you rename a file, you don't have to back trace all the files that reference them. Again this should be programmed. You put the link in normally the first time. A program pulls the links out, puts a 'external reference link' tag in markdown, and adds this to the external link. Ideally it's smart enough taht if you reference something several times, it reuses the tag. Now if you rename or move a file, you only have to fix it in the single external links file. -- Sherwood Botsford Sherwood's Forests Warburg, Alberta T0C 2T0 http://www.sherwoods-forests.com 780-848-2548 ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
re: Table of contents
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) ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: Table of contents
In article , Daniel Winterstein 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 ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: Table of contents
Tables of contents should be generated automatically. Maintaining them by hand especially with electronic documents that are shall we say, a bit unstable, is truly a PITA FrameMaker had (may still have) a feature in which you could abstract the content of styles from your document, and apply a different style to use them in a TOC. E.g. (Adapting language a bit here for the web world) You could extract H1 through H6, stuff them in a file. Then you apply an appropriate CSS to them to make a reasonable looking TOC. Two approaches occur to me: 1. Put a label above headline. Context grep for lines in your markdown files that start with #. Use 1 line of previous context. Perl script turns the label plus the filename into a markdown URL link. grep -r -B1 "^#" tt2 ... tt2/Advice/Design/Landscaping.tt2- tt2/Advice/Design/Landscaping.tt2:# Planning for Change tt2/Advice/Design/Landscaping.tt2: or tt2/Advice/Design/Landscaping.tt2:##Gee, Those Little Trees Look Silly -- tt2/Advice/Design/Landscaping.tt2-don't notice. tt2/Advice/Design/Landscaping.tt2: Lessons: -- tt2/Advice/Design/Design_Principles.tt2- tt2/Advice/Design/Design_Principles.tt2:# Principles of Design. -- tt2/Advice/Design/Design_Principles.tt2- tt2/Advice/Design/Design_Principles.tt2:## Basic principles. -- tt2/Advice/Design/Design_Principles.tt2- tt2/Advice/Design/Design_Principles.tt2: Repetition. -- tt2/Advice/Design/Design_Principles.tt2- tt2/Advice/Design/Design_Principles.tt2: Alternation -- You'll note that I was being clever and cute and used headlines to do something stylistic. My Bad. Approaches you could take for this: * Only index headlines that have a label on them. * multiple successive headlines are glommed together for indexing. If the secondary heads are in different size, then they are shown in parentheses. The otehr approach is to look for the label, then take the line immediately following that. If you are consistent, you would be able to pull lists of figures, photos, tables and equations from your documents this way. -- Sherwood Botsford Sherwood's Forests Warburg, Alberta T0C 2T0 http://www.sherwoods-forests.com 780-848-2548 ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: Table of contents
On Thu, Mar 5, 2009 at 4:27 AM, Daniel Winterstein 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 ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Table of contents
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. 1. First thingy 2. Second thingy 3. Other stuff 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 ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
