Fossil

Timeline
Login

Timeline

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

About branch auto-toc

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

4 check-ins related to "auto-toc"
2020-09-15
20:10
Bug fixes in Pandoc identifier generation. Now closed. See branch wiki for discussion. (Closed-Leaf check-in: 77cbe291 user: drh tags: auto-toc)
19:50
Automatic table-of-contents generated for Markdown if there is a tag of the form: <!--markdown: toc=N --> where N is an integer that is the deepest level of content that will be added to the index. The TOC is inserted in place of the magic HTML comment. (check-in: 6142e11d user: drh tags: auto-toc)
18:20
Enable automatic paragraph numbering in Markdown using a special HTML comment: "<--markdown paragraph-numbers=on -->" (check-in: d9a70a1d user: drh tags: auto-toc)
16:40
fossil.pikchr.addSrcView() now tags each processed SVG element to avoid potentially processing the same one multiple times. Added fossil.pikchr support to /doc, /wiki, and /wikiedit/fileedit previews. This is harmless if there are no pikchrs or JS is disabled. (check-in: 83f03e91 user: stephan tags: trunk)