Skip to content

Latest commit

 

History

History
130 lines (100 loc) · 3.54 KB

README.md

File metadata and controls

130 lines (100 loc) · 3.54 KB

Outline extension for Python-Markdown

Wraps the document logical sections (as implied by h1-h6 headings).

By default, the wrapper element is a section tag having a class attribute "sectionN", where N is the header level being wrapped. Also, the header attributes get moved to the wrapper.

Installation

pip install git+git://github.com/aleray/mdx_outline.git

Usage

>>> import markdown
>>> src = """
... # 1
... Section 1
... ## 1.1
... Subsection 1.1
... ## 1.2
... Subsection 1.2
... ### 1.2.1
... Hey 1.2.1 Special section
... ### 1.2.2
... #### 1.2.2.1
... # 2
... Section 2
... """.strip()
>>> html = markdown.markdown(src, ['outline'])
>>> print(html)
<section class="section1"><h1>1</h1>
<p>Section 1</p>
<section class="section2"><h2>1.1</h2>
<p>Subsection 1.1</p>
</section><section class="section2"><h2>1.2</h2>
<p>Subsection 1.2</p>
<section class="section3"><h3>1.2.1</h3>
<p>Hey 1.2.1 Special section</p>
</section><section class="section3"><h3>1.2.2</h3>
<section class="section4"><h4>1.2.2.1</h4>
</section></section></section></section><section class="section1"><h1>2</h1>
<p>Section 2</p>
</section>

Divs instead of sections, custom class names:

>>> src = """
... # Introduction
... # Body
... ## Subsection
... # Bibliography
... """.strip()
>>> html = markdown.markdown(src, extensions=['outline(wrapper_tag=div, wrapper_cls=s%(LEVEL)d)'])
>>> print(html)
<div class="s1"><h1>Introduction</h1>
</div><div class="s1"><h1>Body</h1>
<div class="s2"><h2>Subsection</h2>
</div></div><div class="s1"><h1>Bibliography</h1>
</div>

By default, the header attributes are moved to the wrappers

>>> src = """
... # Introduction {: foo=bar }
... """.strip()
>>> html = markdown.markdown(src, extensions=['attr_list', 'outline'])
>>> print(html)
<section class="section1" foo="bar"><h1>Introduction</h1>
</section>

Non consecutive headers shouldn't be a problem:

>>> src="""
... # ONE
... ### TOO Deep
... ## Level 2
... # TWO
... """.strip()
>>> html = markdown.markdown(src, extensions=['attr_list', 'outline'])
>>> print(html)
<section class="section1"><h1>ONE</h1>
<section class="section3"><h3>TOO Deep</h3>
</section><section class="section2"><h2>Level 2</h2>
</section></section><section class="section1"><h1>TWO</h1>
</section>

Dependencies

Copyright

All rights reserved.

This software is released under the modified BSD License. See LICENSE.md for details.

Further credits

This is a rewrite of the mdx_addsection extension we've written for active archives. The first version had a bug with non hierachical heading structures. This is no longer a problem: a couple of weeks ago, Jesse Dhillon pushed to github a similar plugin which fixes the problem. Thanks to him, mdx_outline no longer has the problem.

See also