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:
markdown
, latex
, rst
,
mediawiki
, textile
markdown
, muse
markdown
, muse
The default algorithm used to derive the identifier from the heading text is:
section
.Thus, for example,
Heading | Identifier |
---|---|
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.
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.
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. Emojis are replaced by their names.