67 lines
2.1 KiB
Markdown
67 lines
2.1 KiB
Markdown
|
pelican-toc [](https://travis-ci.org/ingwinlu/pelican-toc)
|
||
|
|
===================================
|
||
|
|
|
||
|
|
This plugin generates a table of contents for pelican articles and pages, available for themes via `article.toc`.
|
||
|
|
|
||
|
|
#Usage
|
||
|
|
##requirements
|
||
|
|
Beautifulsoup4 - install via `pip install beautifulsoup4`
|
||
|
|
##theme
|
||
|
|
```
|
||
|
|
{% if article.toc %}
|
||
|
|
<div class="col-lg-3 hidden-xs hidden-sm">
|
||
|
|
{{article.toc}}
|
||
|
|
</div>
|
||
|
|
{% endif %}
|
||
|
|
```
|
||
|
|
##article
|
||
|
|
```
|
||
|
|
Title: Peeking at erlang/chicagoboss
|
||
|
|
###Intro
|
||
|
|
###Chicagoboss Magic
|
||
|
|
###Result
|
||
|
|
```
|
||
|
|
##output
|
||
|
|
```
|
||
|
|
<div class="col-lg-3 hidden-xs hidden-sm">
|
||
|
|
<div id="toc">
|
||
|
|
<ul>
|
||
|
|
<li>
|
||
|
|
<a href="#" title="Peeking at erlang/chicagoboss">Peeking at erlang/chicagoboss</a>
|
||
|
|
<ul>
|
||
|
|
<li>
|
||
|
|
<a href="#intro" title="Intro">Intro</a>
|
||
|
|
</li>
|
||
|
|
<li>
|
||
|
|
<a href="#chicagoboss-magic" title="Chicagoboss Magic">Chicagoboss Magic</a>
|
||
|
|
</li>
|
||
|
|
<li>
|
||
|
|
<a href="#result" title="Result">Result</a>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
```
|
||
|
|
|
||
|
|
##settings
|
||
|
|
```
|
||
|
|
TOC = {
|
||
|
|
'TOC_HEADERS' : '^h[1-6]', # What headers should be included in the generated toc
|
||
|
|
# Expected format is a regular expression
|
||
|
|
|
||
|
|
'TOC_RUN' : 'true' # Default value for toc generation, if it does not evaluate
|
||
|
|
# to 'true' no toc will be generated
|
||
|
|
}
|
||
|
|
```
|
||
|
|
All those settings can be overwritten on a per page/article basis via metadata.
|
||
|
|
Just use the respective keyword as metadata (example: `toc_headers: ^h[1-4]`)
|
||
|
|
|
||
|
|
#Differences between pelican-toc and pelican-extract-toc
|
||
|
|
`extract-toc` uses a markdown extension to generate a toc and then extract it via beautifulsoup.
|
||
|
|
This extension generates the toc itself, removing the need to write `[ToC]` in your articles.
|
||
|
|
There also is a 'health' check on id's which should be generated via markdown.extensions.headerid per default, but somehow don't always end up in the output.
|
||
|
|
|
||
|
|
|