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.7)

Designed for use with MkDocs

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

Installation 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.

Source Distribution

ocxsect-0.1.4.tar.gz (4.9 kB view details)

Uploaded Source

Built Distribution

ocxsect-0.1.4-py2.py3-none-any.whl (9.0 kB view details)

Uploaded Python 2Python 3

File details

Details for the file ocxsect-0.1.4.tar.gz.

File metadata

  • Download URL: ocxsect-0.1.4.tar.gz
  • Upload date:
  • Size: 4.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/40.6.3 requests-toolbelt/0.9.1 tqdm/4.33.0 CPython/3.6.7

File hashes

Hashes for ocxsect-0.1.4.tar.gz
Algorithm Hash digest
SHA256 81e7c3df97fa06e73eb96404a1c2eabc71ad91747a00a7be7f5407560d5e7069
MD5 6ba9b1817be0f9c3d77ef9480ccd4041
BLAKE2b-256 d2a48da8732a0b26d392a52212d599eb5852031011b2ff6ea10e27f97859cdfc

See more details on using hashes here.

File details

Details for the file ocxsect-0.1.4-py2.py3-none-any.whl.

File metadata

  • Download URL: ocxsect-0.1.4-py2.py3-none-any.whl
  • Upload date:
  • Size: 9.0 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/40.6.3 requests-toolbelt/0.9.1 tqdm/4.33.0 CPython/3.6.7

File hashes

Hashes for ocxsect-0.1.4-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 0063f93e570b51d4f5ff2eda8b53c82c094c3e4c7cf5bb003219f963a16e0108
MD5 8b4af03c2991e1df61c34a2a69f18943
BLAKE2b-256 c6c481e46db8c58b3d687445f6647a0894ad5726f5e2b410acca4d1695e63f83

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page