Headings and sections
Extension: auto_identifiers
A heading without an explicitly specified identifier will be automatically assigned a unique identifier based on the heading text.
This extension can be enabled/disabled for the following formats:
- input formats
markdown
, latex
, rst
, mediawiki
, textile
- output formats
markdown
, muse
- enabled by default in
markdown
, muse
The default algorithm used to derive the identifier from the heading text is:
- Remove all formatting, links, etc.
- Remove all footnotes.
- Remove all non-alphanumeric characters, except underscores, hyphens, and periods.
- Replace all spaces and newlines with hyphens.
- Convert all alphabetic characters to lowercase.
- Remove everything up to the first letter (identifiers may not begin with a number or punctuation mark).
- If nothing is left after this, use the identifier
section
.
Thus, for example,
Heading identifiers in HTML |
heading-identifiers-in-html |
Maître d'hôtel |
maître-dhôtel |
*Dogs*?--in *my* house? |
dogs--in-my-house |
[HTML], [S5], or [RTF]? |
html-s5-or-rtf |
3. Applications |
applications |
33 |
section |
These rules should, in most cases, allow one to determine the identifier from the heading text. The exception is when several headings have the same text; in this case, the first will get an identifier as described above; the second will get the same identifier with -1
appended; the third with -2
; and so on.
(However, a different algorithm is used if gfm_auto_identifiers
is enabled; see below.)
These identifiers are used to provide link targets in the table of contents generated by the --toc|--table-of-contents
option. They also make it easy to provide links from one section of a document to another. A link to this section, for example, might look like this:
See the section on
[heading identifiers](#heading-identifiers-in-html-latex-and-context).
Note, however, that this method of providing links to sections works only in HTML, LaTeX, and ConTeXt formats.
If the --section-divs
option is specified, then each section will be wrapped in a section
(or a div
, if html4
was specified), and the identifier will be attached to the enclosing <section>
(or <div>
) tag rather than the heading itself. This allows entire sections to be manipulated using JavaScript or treated differently in CSS.
Extension: ascii_identifiers
Causes the identifiers produced by auto_identifiers
to be pure ASCII. Accents are stripped off of accented Latin letters, and non-Latin letters are omitted.
Extension: gfm_auto_identifiers
Changes the algorithm used by auto_identifiers
to conform to GitHub’s method. Spaces are converted to dashes (-
), uppercase characters to lowercase characters, and punctuation characters other than -
and _
are removed.