D 2020-09-15T20:57:17.300
L branch/auto-toc
N text/x-markdown
U drh
W 2382
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](forum:/forumpost/b635dc56cb)
* [markdown-header-ids branch](/timeline?r=markdown-header-ids)
* [RFC: adding auto-generating ID attributes in markdown-to-html heading elements](forum:/forumpost/097eca7dd9)
Z 74370ce10248cfa508c9fa982162eb1b