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](https://github.com/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.

```bash
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](http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents) for more details.

```rst
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](http://pythonhosted.org/Markdown/extensions/toc.html) 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.

```Markdown
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
================

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