blob: 82e8e2cd19f235e6eac83fc21d2e2cc46c50df1b (
plain)
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
127
128
129
130
131
|
title: HeaderId Extension
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.md
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`:
```md
#Header
#Header
#Header
```
Results in:
```html
<h1 id="header">Header</h1>
<h1 id="header_1">Header</h1>
<h1 id="header_2">Header</h1>
```
Usage
-----
See [Extensions](index.md) for general extension usage, specify
`markdown.extensions.headerid` as the name of the extension.
See the [Library Reference](../reference.md#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:
:::pycon
>>> 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.md) extension).
:::pycon
>>> 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.md) 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:
```md
header_level: 2
header_forceid: Off
# A Header
```
Will result in the following output:
```html
<h2>A Header</h2>
```
|
