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