Adds Extract table of contents plugin

extract_toc/README.md

@@ -0,0 +1,66 @@
+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.
+
+Template Example
+================
+
+```python
+{% if article.toc %}
+    <nav class="affix">
+    {{ article.toc }}
+    </nav>
+{% endif %}
+```

extract_toc/__init__.py

@@ -0,0 +1 @@
+from .extract_toc import *

extract_toc/extract_toc.py

@@ -0,0 +1,32 @@
+"""
+Extract Table of Content
+========================
+
+This plugin allows you to extract table of contents (ToC) from article.content
+and place it in its own article.toc variable.
+"""
+
+from os import path
+from bs4 import BeautifulSoup
+from pelican import signals, readers
+
+
+def extract_toc(content):
+    soup = BeautifulSoup(content._content)
+    filename = content.source_path
+    extension = path.splitext(filename)[1][1:]
+    toc = ''
+    # if it is a Markdown file
+    if extension in readers.MarkdownReader.file_extensions:
+        toc = soup.find('div', class_='toc')
+    # else if it is a reST file
+    elif extension in readers.RstReader.file_extensions:
+        toc = soup.find('div', class_='contents topic')
+    if toc:
+        toc.extract()
+        content._content = soup.decode()
+        content.toc = toc.decode()
+
+
+def register():
+    signals.content_object_init.connect(extract_toc)