138 lines
3.5 KiB
Markdown
138 lines
3.5 KiB
Markdown
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](https://github.com/avaris) for going out of the way to help
|
|
me fix Unicode issues and doing a thorough code review.
|
|
|
|
Thanks to [gw0](http://gw.tnode.com/) 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.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```python
|
|
{% 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](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 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](http://pythonhosted.org/Markdown/extensions/toc.html) for more details.
|
|
|
|
```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.
|
|
```
|
|
|
|
|
|
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`:
|
|
|
|
```html
|
|
$if(toc)$
|
|
<nav id="TOC">
|
|
$toc$
|
|
</nav>
|
|
$endif$
|
|
$body$
|
|
```
|