Home | History | Annotate | Download | only in extensions 
      1 HeaderId
      2 ========
      3 
      4 Summary
      5 -------
      6 
      7 An extension to Python-Markdown that adds an 'id' attribute to HTML header 
      8 elements (h1-h6) in markdown's output.
      9 
     10 This extension is included in the standard Markdown library.
     11 
     12 Syntax
     13 ------
     14 
     15 The 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 
     24 will result in the following HTML:
     25 
     26     <h1 id="header1">Header 1</h1>
     27 
     28     <h2 id="header2">Header 2</h2>
     29 
     30 However, there is much more that this extension does.
     31 
     32 By default, all headers will automatically have unique "id" attributes 
     33 generated based upon the text of the header (See below to turn this off). 
     34 Note this example in which all three headers would have the same "id":
     35 
     36     #Header
     37     #Another Header {#header}
     38     #Header
     39 
     40 Results 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 
     46 Configuring the Output
     47 ----------------------
     48 
     49 The 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 
     59 The `level` setting allows you to automatically adjust the header levels to fit
     60 within the hierarchy of your html templates. For example, the markdown text for
     61 this page should not contain any headers higher than level 3 (`<h3>`). 
     62 Therefore, 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 
     72 The `forceid` setting turns on or off the automatically generated ids for 
     73 headers 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 
     83 Using with Meta-Data
     84 --------------------
     85 
     86 The 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 
     91 When used, the meta-data will override the settings provided through the  
     92 `extension_configs` interface. 
     93 
     94 This document:
     95 
     96     header_level: 2
     97     header_forceid: Off
     98 
     99     # A Header
    100 
    101 
    102 Will result in the following output:
    103 
    104     <h2>A Header</h2>
    105