Switch branches/tags
Nothing to show
Find file History
bnice5000 bnice5000
bnice5000 and bnice5000 [extract_toc] Fix pandoc_reader Issue
Fixes #582

toc_extract assumes that if it can import pandoc_reader that
pandoc_reader is configured. This is not always the case and can cause
an error as pandoc_reader requires pelicanonf parameter.

This fix adds a plugin check to make sure that pandoc_reader was meant
to be called by having it as a configured setting.
Latest commit a1fbd88 Jun 5, 2016

README.md

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 for use in templates.

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.

Thanks to gw0 for adding Pandoc reader support.

Why do you need it?

Pelican can generate ToC of reST and Markdown files, using markup's respective directive and extension. Such ToC is generated and placed at the beginning of article.content like a string. Consequently it can not be placed anywhere else on the page (eg. <nav> HTML5 tag, in header, or at the end of your article's contents).

To solve this problem, this plugin extracts ToC from article.content and places it in its own article.toc variable for use in templates.

Requirements

extract_toc requires BeautifulSoup.

pip install beautifulsoup4

How to Use

This plugin works by extracting the first occurrence of enclosed in:

  • <div class="toc"> for the default Markdown reader
  • <div class="contents topic"> for the default reStructuredText reader
  • <nav class="TOC"> for the Pandoc reader

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.

Template example

Add something like this to your Pelican templates if missing:

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

reStructuredText reader

To add a table of contents to your reStructuredText document (.rst) you need to add a .. contents:: directive to its beginning. See the docutils 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 reader

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

To add a table of contents to your Markdown document (.md) you need to place the [TOC] marker to its beginning. See the Python Markdown documentation for more details.

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.

Pandoc reader

To enable table of contents generation for the Pandoc reader you need to set PANDOC_ARGS = (['--toc', '--template=pandoc-template-toc']) in your Pelican configuration file.

Contents of the Pandoc template file pandoc-template-toc.html5:

$if(toc)$
<nav id="TOC">
$toc$
</nav>
$endif$
$body$