/usr/share/doc/python-markdown-doc/docs/extensions/header_id.txt is in python-markdown-doc 2.6.9-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 | title: HeaderId Extension
prev_title: CodeHilite Extension
prev_url: code_hilite.html
next_title: Meta-Data Extension
next_url: meta_data.html
HeaderId
========
Summary
-------
The HeaderId extension automatically generates `id` attributes for the header
elements (`h1`-`h6`) in the resulting HTML document.
This extension is included in the standard Markdown library.
!!! warning
This extension is **Pending Deprecation**. The [Table of Contents][toc]
Extension should be used instead, which offers most the features of this
extension and more.
[toc]: toc.html
Syntax
------
By default, all headers will automatically have unique `id` attributes
generated based upon the text of the header (see below to turn this off).
Note this example, in which all three headers would have the same `id`:
#Header
#Header
#Header
Results in:
<h1 id="header">Header</h1>
<h1 id="header_1">Header</h1>
<h1 id="header_2">Header</h1>
Usage
-----
See [Extensions](index.html) for general extension usage, specify `markdown.extensions.headerid`
as the name of the extension.
See the [Library Reference](../reference.html#extensions) for information about
configuring extensions.
The following options are provided to configure the output:
* **`level`**: Base level for headers.
Default: `1`
The `level` setting allows you to automatically adjust the header levels to
fit within the hierarchy of your HTML templates. For example, suppose the
markdown text for a page should not contain any headers higher than level 3
(`<h3>`). The following will accomplish that:
>>> text = '''
... #Some Header
... ## Next Level'''
>>> from markdown.extensions.headerid import HeaderIdExtension
>>> html = markdown.markdown(text, extensions=[HeaderIdExtension(level=3)])
>>> print html
<h3 id="some_header">Some Header</h3>
<h4 id="next_level">Next Level</h4>'
* **`forceid`**: Force all headers to have an id.
Default: `True`
The `forceid` setting turns on or off the automatically generated ids for
headers that do not have one explicitly defined (using the
[Attribute List](attr_list.html) extension).
>>> text = '''
... # Some Header
... # Header with ID # { #foo }'''
>>> html = markdown.markdown(text,
extensions=['markdown.extensions.attr_list',
HeaderIdExtension(forceid=False)])
>>> print html
<h1>Some Header</h1>
<h1 id="foo">Header with ID</h1>
* **`separator`**: Word separator. Character which replaces white space in id.
Default: `-`
* **`slugify`**: Callable to generate anchors.
Default: `markdown.extensions.headerid.slugify`
If you would like to use a different algorithm to define the ids, you can
pass in a callable which takes two arguments:
* `value`: The string to slugify.
* `separator`: The Word Separator.
Using with Meta-Data
--------------------
The HeaderId extension also supports the [Meta-Data](meta_data.html) extension.
Please see the documentation for that extension for specifics. The supported
meta-data keywords are:
* `header_level`
* `header_forceid`
When used, the meta-data will override the settings provided through the
`extension_configs` interface.
This document:
header_level: 2
header_forceid: Off
# A Header
Will result in the following output:
<h2>A Header</h2>
|