| Current File : //usr/share/doc/python2-markdown-2.4.1/extensions/header_id.html |
<!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>