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

Header

Header

Header

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

`). The following will accomplish that: >>> text = ''' ... #Some Header ... ## Next Level''' >>> html = markdown.markdown(text, extensions=['headerid(level=3)']) >>> print html

Some Header

Next Level

' * **`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=['attr_list', 'headerid(forceid=False)']) >>> print html

Some Header

Header with ID

* **`separator`**: Word separator. Character which replaces whitespace 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:

A Header