docs/extensions/HeaderId.txt

HeaderId
========

Summary
-------

An extension to Python-Markdown that adds an 'id' attribute to HTML header 
elements (h1-h6) in markdown's output.

This extension is included in the standard Markdown library.

Syntax
------

The basic syntax follows [PHP Markdown Extra][]'s implementation:

[PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/#header-id

    Header 1            {#header1}
    ========

    ## Header 2 ##      {#header2}

will result in the following HTML:

    <h1 id="header1">Header 1</h1>

    <h2 id="header2">Header 2</h2>

However, there is much more that this extension does.

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
    #Another Header {#header}
    #Header

Results in:

    <h1 id="header">Header</h1>
    <h1 id="header_1">Another Header</h1>
    <h1 id="header_2">Third Header</h1>

Configuring the Output
----------------------

The HeaderId extension has two configuration settings:

* **level**: Base level for headers.

    Default: `1`

* **forceid**: Force all headers to have an id.

    Default: `True`

The `level` setting allows you to automatically adjust the header levels to fit
within the hierarchy of your html templates. For example, the markdown text for
this page should not contain any headers higher than level 3 (`<h3>`). 
Therefore, do the following:

    >>>  text = '''
    ... #Some Header
    ... ## Next Level'''
    >>> html = markdown.markdown(text, ['headerid(level=3)'])
    >>> print html
    <h3 id="some_header">Some Header</h3>
    <h4 id="next_level">Next Level</h4>'

The `forceid` setting turns on or off the automatically generated ids for 
headers that do not have one explicitly defined.

    >>> text = '''
    ... # Some Header
    ... # Header with ID # { #foo }'''
    >>> html = markdown.markdown(text, ['headerid(forceid=False)'])
    >>> print html
    <h1>Some Header</h1>
    <h1 id="foo">Header with ID</h1>

Using with Meta-Data
--------------------

The HeaderId Extension also supports the [[Meta-Data]] 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>