Fossil

The idea demonstrated by this branch is to automatically generate a table-of-contents and paragraph numbers for a markdown document. The branch also generates Pandoc-style identifiers on every header.

The branch works (or seems to) but I think I'm going to abandon it for reasons described below.

How it works.

To turn automatic paragraph numbering on or off, add an HTML comment of the following form:

     <!--markdown: paragraph-numbers=ON -->

Or OFF or some numbers. If the setting is set to a number, then it is assumed that no headers of lower levels are ever generated, and so a corresponding number of terms are removed from the front of each paragraph number. Thus if if paragraph-numbers=3 and you have a "<h5>" heading, that heading gets a number like 1.2.3 instead of 1.2.3.4.5 as it would normally.

For a table of contents, insert a comment like this:

    <!--markdown: toc=3 -->

Replace the "3" with the number of levels of content that you want to include in the TOC. The TOC replaces the comment. This is done on a second pass, so the TOC can (and usually does) reference sections of the document that come after the TOC.

This branch also always generated identifiers for each heading based on the heading name, and following the general idea of how Pandoc generates its identifiers, though with perhaps some minor differences in detail.

Why Abandon This Change?

After putting this all together and experimenting with it, it seems like it is just extra complication. Markdown and other similar markup formats are intended to be simple. These changes are just extra complication used to insert extra boilerplate text. If you need automatic paragraph numbers and/or a TOC, perhaps you should consider using a different tool. In other words, I think this change goes against the whole philosophy of Markdown, which is to provide a simple and easy way to generate simple, readable documentation. We should not be trying to push Markdown into being a replacement for MS-Office.

Cross-references

• Automatic TOC, paragraph numbering, and header IDs
• markdown-header-ids branch
• RFC: adding auto-generating ID attributes in markdown-to-html heading elements
• docindex.tcl script, provides similar functionality