Skip to main content

A python markdown extension that allows you to add semantic HTML5 sectioning elements into the generated html.

Project description

Build Status Coverage

Sectioning in markdown

An extension to python markdown that allows you to add semantic HTML5 sectioning elements into the generated html by putting strings such as ~~S~~ at the start of a section and ~~/S~~ at the end. Sectioning elements supported are <section>, <chapter>, <header>, <footer>, <nav>, <div>, and <article>. These can be given identifiers by adding text after the sectioning element letter, e.g. ~~S section1~~ to give <section id="section1">. A schematic representation of the structure (useful for debugging) is also generated and stored as the markdown.Markdown.tree_diagram property of the markdown object.

Requirements & dependencies

Python 3 (tested on Python 3.6 and 3.7)

Designed for use with MkDocs

Uses python packages Python-Markdown, Python re, xml.etree.ElementTree and re - Regular expression operations

Installation from github source with setup.py requires setuptools

Doesn't play nicely with other python markdown extensions that use ~~~ to delineate markup, notably it can lead to text being shown as struck through.

Installation

Warning: The xml.etree.ElementTree module is not secure against maliciously constructed data. If you need to parse untrusted or unauthenticated data see XML vulnerabilities.

Warning: exercise caution this early release software with no warranty, test this first in a virtual environment!

Install from pypi:

(venv)$ pip install ocxsect

Or install from github:

(venv)$ git clone https://github.com/philbarker/ocxsect.git
(venv)$ cd ocxsect
(venv)$ python setup.py test
(venv)$ python setup.py install
(venv)$ python test.py

Usage

To create a new section put ~~X~~ on a line by itself, where X represents the type of HTML5 sectioning element you want to create. Sectioning elements supported are section (S), chapter (C) header (H) footer (F) nav (N) div (D) and article (A). These can be given identifiers by add text after the sectioning element letter, e.g. ~~S lesson1~~. In order to avoid non-URL safe characters in the identifier any character not in the set A-Z, a-z, 0-9, !$-()+ is removed. So ~~A #activity 1~~ becomes <article id="activity1">.

Usage in MkDocs

After installation, add ocxsect to your extensions block in mkdocs.yml:

markdown_extensions:
  - ocxsect

Example

Markdown input

~~C lesson1~~

~~H~~
#Markdown structure test
This is in the header section of a chapter. The chapter has id #lesson1. The header has no id.

~~/H~~

~~S section 1~~
#Activity 1
This is in a regular section (id #section1) of a chapter

~~/S~~

~~F~~

This is in the footer of the chapter

~~/F~~

~~/C~~

Schematic representation of structure

|--chapter{'id': 'lesson1'}
    |--header
        |--h1
        |--p
    |--section{'id': 'section1'}
        |--h1
        |--p
    |--footer
        |--p
|--p

HTML output

<chapter id="lesson1">
  <header>
    <h1>Markdown structure test</h1>
    <p>This is in the header section of a chapter. The chapter has id #lesson1. The header has no id.</p>
  </header>
  <section id="section1">
    <h1>Activity 1</h1>
    <p>This is in a regular section (id #section1) of a chapter</p>
  </section>
  <footer>
    <p>This is in the footer of the chapter</p>
  </footer>
</chapter>
<p>This is after the chapter</p>

See test.py for a fully working example embedded in markdown.

Project details


Download files

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

Files for ocxsect, version 0.1.5
Filename, size File type Python version Upload date Hashes
Filename, size ocxsect-0.1.5-py2.py3-none-any.whl (9.0 kB) File type Wheel Python version py2.py3 Upload date Hashes View hashes
Filename, size ocxsect-0.1.5.tar.gz (4.9 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page