67 lines
1.8 KiB
Markdown
67 lines
1.8 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.
|
|
|
|
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 %}
|
|
```
|