Skip to main content
Join the official 2020 Python Developers SurveyStart the survey!

Python-Markdown extension to add a small amount of structure to Markdown documents.

Project description



This module is an extension to Python-Markdown which provides the ability to add a small amount of structure to your Markdown documents.

There are two premises underlying the operation of this extension:

  • Each heading element indicates the start of a new document section.
  • Document sections can be nested, and the parent of a document section is the section created by the first preceding heading element with a higher order e.g. an h2 section is contained by the heading block appearing prior to it which corresponds to an h1. If there is no such element, then it is a child of the root element.

The new section (a containing div element) can be configured to have an specific id and class attribute. The syntax is:

# {id,class} Title

Both id and class are optional, the contaaining div element will always be created as long as this extension is enabled.

One example should make this clear. Suppose the following input document is provided:

# {resume} Resumé

## {education} Education
Educational experience

## {experience} Working Experience
Work experience

### {xyz_corp,employer} XYZ Corp.
I worked at XYZ

### {acme_inc,employer} Acme Inc.
I also worked at Acme

## Hobbies
- Cards
- Books
- Dogs

### About _my_ hobbies
My hobbies are great.

This would transform to become:

<div class="section" id="section_resume">
  <h1 class="title">Resum&eacute;</h1>
  <div class="section" id="section_education">
    <h2 class="title">Education</h2>
    <p>Educational experience</p>
  <div class="section" id="section_experience">
    <h2 class="title">Working Experience</h2>
    <p>Work experience</p>
    <div class="employer" id="section_xyz_corp">
      <h3 class="title">XYZ Corp.</h3>
      <p>I worked at XYZ</p>
    <div class="employer" id="section_acme_inc">
      <h3 class="title">Acme Inc.</h3>
      <p>I also worked at Acme</p>
  <div class="section">
    <h2 class="title">Hobbies</h2>
    <div class="section">
      <h3 class="title">About <em>my</em> hobbies</h3>
      <p>My hobbies are great.</p>

The resulting document is, IMO, semantically correct. It’s also easier to style with CSS.


Install using setuptools, e.g. (within a virtualenv):

$ pip install mdx_sections

Or if you prefer to get the latest from Github:

$ git clone git://


For an extended introduction to Python-Markdown extensions, see the documentation

This extension is available by the short name of sections, and it has two config parameters:

  • section_cls, defaults to section. This is the default CSS class applied to a generated div, when the Markdown document does not specify one.
  • heading_cls, defaults to title. This is the default CSS class applied to the h[1-6] element which is being transformed.



22 Feb 2012

  • Initial public release.

Project details

Release history Release notifications | RSS feed

This version


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for mdx_sections, version 0.1
Filename, size File type Python version Upload date Hashes
Filename, size mdx_sections-0.1.tar.gz (4.1 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page