<!DOCTYPE html> <html> <head> <meta charset=utf-8> <title>HeaderId Extension — Python Markdown</title> <link rel="stylesheet" href="../default.css" type="text/css"> </head> <body> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="../siteindex.html" title="General Index">index</a></li> <li class="right"> <a href="meta_data.html" title="Meta-Data Extension" accesskey="N">next</a> |</li> <li class="right"> <a href="code_hilite.html" title="CodeHilite Extension" accesskey="P">previous</a> |</li> <li><img src="../py.png" alt="" style="vertical-align: middle; margin-top: -1px"/></li> <li><a href="../index.html">Python Markdown v2.4.1 documentation</a> »</li> <li><a href="index.html">Extensions</a> »</li> <li><a href="header_id.html">HeaderId Extension</a> »</li> </ul> </div> <!-- .related --> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body"> <h1 id="headerid">HeaderId<a class="headerlink" href="#headerid" title="Permanent link">¶</a></h1> <h2 id="summary">Summary<a class="headerlink" href="#summary" title="Permanent link">¶</a></h2> <p>The HeaderId extension automatically generates <code>id</code> attributes for the header elements (<code>h1</code>-<code>h6</code>) in the resulting HTML document.</p> <p>This extension is included in the standard Markdown library.</p> <h2 id="syntax">Syntax<a class="headerlink" href="#syntax" title="Permanent link">¶</a></h2> <p>By default, all headers will automatically have unique <code>id</code> 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 <code>id</code>:</p> <pre><code>#Header #Header #Header </code></pre> <p>Results in:</p> <pre><code><h1 id="header">Header</h1> <h1 id="header_1">Header</h1> <h1 id="header_2">Header</h1> </code></pre> <h2 id="usage">Usage<a class="headerlink" href="#usage" title="Permanent link">¶</a></h2> <p>See <a href="index.html">Extensions</a> for general extension usage, specify <code>headerid</code> as the name of the extension.</p> <p>See the <a href="../reference.html#extensions">Library Reference</a> for information about configuring extensions.</p> <p>The following options are provided to configure the output:</p> <ul> <li> <p><strong><code>level</code></strong>: Base level for headers.</p> <p>Default: <code>1</code></p> <p>The <code>level</code> 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 (<code><h3></code>). The following will accomplish that:</p> <pre><code>>>> text = ''' ... #Some Header ... ## Next Level''' >>> html = markdown.markdown(text, extensions=['headerid(level=3)']) >>> print html <h3 id="some_header">Some Header</h3> <h4 id="next_level">Next Level</h4>' </code></pre> </li> <li> <p><strong><code>forceid</code></strong>: Force all headers to have an id.</p> <p>Default: <code>True</code></p> <p>The <code>forceid</code> setting turns on or off the automatically generated ids for headers that do not have one explicitly defined (using the <a href="attr_list.html">Attribute List</a> extension).</p> <pre><code>>>> text = ''' ... # Some Header ... # Header with ID # { #foo }''' >>> html = markdown.markdown(text, extensions=['attr_list', 'headerid(forceid=False)']) >>> print html <h1>Some Header</h1> <h1 id="foo">Header with ID</h1> </code></pre> </li> <li> <p><strong><code>separator</code></strong>: Word separator. Character which replaces whitespace in id.</p> <p>Default: <code>-</code></p> </li> <li> <p><strong><code>slugify</code></strong>: Callable to generate anchors.</p> <p>Default: <code>markdown.extensions.headerid.slugify</code></p> <p>If you would like to use a different algorithm to define the ids, you can pass in a callable which takes two arguments:</p> <ul> <li><code>value</code>: The string to slugify.</li> <li><code>separator</code>: The Word Separator.</li> </ul> </li> </ul> <h2 id="using-with-meta-data">Using with Meta-Data<a class="headerlink" href="#using-with-meta-data" title="Permanent link">¶</a></h2> <p>The HeaderId extension also supports the <a href="meta_data.html">Meta-Data</a> extension. Please see the documentation for that extension for specifics. The supported meta-data keywords are:</p> <ul> <li><code>header_level</code></li> <li><code>header_forceid</code></li> </ul> <p>When used, the meta-data will override the settings provided through the<br /> <code>extension_configs</code> interface. </p> <p>This document:</p> <pre><code>header_level: 2 header_forceid: Off # A Header </code></pre> <p>Will result in the following output:</p> <pre><code><h2>A Header</h2> </code></pre> </div> <!-- .body --> </div> <!-- .bodywrapper --> </div> <!-- .documentwrapper --> <div class="sphinxsidebar"> <div class="sphinxsidebarwrapper"> <h3>Table Of Contents</h3> <div class="toc"> <ul> <li><a href="#headerid">HeaderId</a><ul> <li><a href="#summary">Summary</a></li> <li><a href="#syntax">Syntax</a></li> <li><a href="#usage">Usage</a></li> <li><a href="#using-with-meta-data">Using with Meta-Data</a></li> </ul> </li> </ul> </div> <h4>Previous topic</h4> <p class="topless"><a href="code_hilite.html" title="previous chapter">CodeHilite Extension</a></p> <h4>Next topic</h4> <p class="topless"><a href="meta_data.html" title="next chapter">Meta-Data Extension</a></p> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="https://github.com/waylan/Python-Markdown/issues" >Report a Bug</a></li> <li><a href="header_id.txt" rel="nofollow">Show Source</a></li> </ul> </div> <!-- .sphinxsidebarwrapper --> </div> <!-- .sphinxsidebar --> <div class="clearer"></div> </div> <!-- .document --> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="../siteindex.html" title="General Index">index</a></li> <li class="right"> <a href="meta_data.html" title="Meta-Data Extension" accesskey="N">next</a> |</li> <li class="right"> <a href="code_hilite.html" title="CodeHilite Extension" accesskey="P">previous</a> |</li> <li><img src="../py.png" alt="" style="vertical-align: middle; margin-top: -1px"/></li> <li><a href="../index.html">Python Markdown v2.4.1 documentation</a> »</li> <li><a href="index.html">Extensions</a> »</li> <li><a href="header_id.html">HeaderId Extension</a> »</li> </ul> </div> <!-- .related --> <div class="footer">© 2010-2012 Python Markdown Project</div> </body> </html>