pelican-plugins/extract_toc

Extract Table of Content

A Pelican plugin to extract table of contents (ToC) from article.content and place it in its own article.toc variable.

Copyright (c) Talha Mansoor

Author	Talha Mansoor
Author Email	talha131@gmail.com
Author Homepage	http://onCrashReboot.com
Github Account	https://github.com/talha131

Acknowledgement

Thanks to Avaris for going out of the way to help me fix Unicode issues and doing a thorough code review.

Why do you need it?

Pelican can generate ToC of reST and Markdown files, using markup's respective directive and extension. ToC is generated and placed at the beginning of article.content. You cannot place the ToC in <nav> HTML5 tag, nor can you place the ToC at the end of your article's content because ToC is part of article.content.

This plugin extracts ToC from article.content and places it in article.toc.

Requirements

extract_toc requires BeautifulSoup.

pip install beautifulsoup4

How to Use

Important! This plugin only works with reST and Markdown files. reST files should have .rst extension. Markdown files can have .md, .mkd or markdown.

If ToC appears in your article at more than one places, extract_toc will remove only the first occurrence. You shouldn't probably need to have multiple ToC in your article. In case you need to display it multiple times, you can print it via your template.

ToC generated by Markdown is enclosed in <div class="toc">. On the other hand ToC generated by reST is enclosed in <div class="contents topic">. extract_toc relies on this behavior to work.

reStructuredText Example

To add a table of contents to your reStructuredText document you need to add a 'contents directive' at the place where you want the table of contents to appear. See the documentation for more details.

My super title
##############

:date: 2010-10-03
:tags: thats, awesome

.. contents::
..
   1  Head 1
     1.1  Head 2
   2  Head 3
   3  head 4

Heading 1
---------

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa.

Markdown Example

To add a table of contents to your Markdown document you need to place the 'TOC marker' at the place where you would like the table of contents to appear. See the Python Markdown documentation for more details.

Important! To enable table of contents generation for the markdown reader you need to set MD_EXTENSIONS = (['toc']) in your pelican configuration file.

title: My super title
date: 4-4-2013
tags: thats, awesome

[TOC]

# Heading 1 #

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa.

Template Example

{% if article.toc %}
    <nav class="affix">
    {{ article.toc }}
    </nav>
{% endif %}