cygnal-blog/plugins/toc

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&nbsp;erlang/chicagoboss">Peeking at&nbsp;erlang/chicagoboss</a>
          <ul>
            <li>
              <a href="#intro" title="Intro">Intro</a>
            </li>
            <li>
              <a href="#chicagoboss-magic" title="Chicagoboss&nbsp;Magic">Chicagoboss&nbsp;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.