1HeaderId
2========
3
4Summary
5-------
6
7An extension to Python-Markdown that adds an 'id' attribute to HTML header
8elements (h1-h6) in markdown's output.
9
10This extension is included in the standard Markdown library.
11
12Syntax
13------
14
15The basic syntax follows [PHP Markdown Extra][]'s implementation:
16
17[PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/#header-id
18
19    Header 1            {#header1}
20    ========
21
22    ## Header 2 ##      {#header2}
23
24will result in the following HTML:
25
26    <h1 id="header1">Header 1</h1>
27
28    <h2 id="header2">Header 2</h2>
29
30However, there is much more that this extension does.
31
32By default, all headers will automatically have unique "id" attributes
33generated based upon the text of the header (See below to turn this off).
34Note this example in which all three headers would have the same "id":
35
36    #Header
37    #Another Header {#header}
38    #Header
39
40Results in:
41
42    <h1 id="header">Header</h1>
43    <h1 id="header_1">Another Header</h1>
44    <h1 id="header_2">Third Header</h1>
45
46Configuring the Output
47----------------------
48
49The HeaderId extension has two configuration settings:
50
51* **level**: Base level for headers.
52
53    Default: `1`
54
55* **forceid**: Force all headers to have an id.
56
57    Default: `True`
58
59The `level` setting allows you to automatically adjust the header levels to fit
60within the hierarchy of your html templates. For example, the markdown text for
61this page should not contain any headers higher than level 3 (`<h3>`).
62Therefore, do the following:
63
64    >>>  text = '''
65    ... #Some Header
66    ... ## Next Level'''
67    >>> html = markdown.markdown(text, ['headerid(level=3)'])
68    >>> print html
69    <h3 id="some_header">Some Header</h3>
70    <h4 id="next_level">Next Level</h4>'
71
72The `forceid` setting turns on or off the automatically generated ids for
73headers that do not have one explicitly defined.
74
75    >>> text = '''
76    ... # Some Header
77    ... # Header with ID # { #foo }'''
78    >>> html = markdown.markdown(text, ['headerid(forceid=False)'])
79    >>> print html
80    <h1>Some Header</h1>
81    <h1 id="foo">Header with ID</h1>
82
83Using with Meta-Data
84--------------------
85
86The HeaderId Extension also supports the [[Meta-Data]] Extension. Please see the documentation for that extension for specifics. The supported meta-data keywords are:
87
88* `header_level`
89* `header_forceid`
90
91When used, the meta-data will override the settings provided through the
92`extension_configs` interface.
93
94This document:
95
96    header_level: 2
97    header_forceid: Off
98
99    # A Header
100
101
102Will result in the following output:
103
104    <h2>A Header</h2>
105