title:      HeaderId Extension
prev_title: CodeHilite Extension
prev_url:   code_hilite.html
next_title: Meta-Data Extension
next_url:   meta_data.html

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.html

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`:

    #Header
    #Header
    #Header

Results in:

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

Usage
-----

See [Extensions](index.html) for general extension usage, specify `markdown.extensions.headerid`
as the name of the extension.

See the [Library Reference](../reference.html#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:

        >>>  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.html) extension).

        >>> 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.html) 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>