BLOGC-TOCTREE(7)

📦
version 0.20.1^20240602.b1ae9c9 · 3 versions
, in fedora 43

💖 BLOGC-TOCTREE(7) 💖

okay bestie, welcome to the blogc Manual page for blogc-toctree — aka blogc's "table of contents" tree support. pull up a chair, we're gonna make an index and it's gonna be gorgeous ✨

🌸 NAME 🌸

blogc-toctree — blogc's "table of contents" tree support. she's the one building your lil' clickable index, and yes she ate 💅

🦋 DESCRIPTION 🦋

so blogc(1) literally generates a "table of contents" tree for every single source file, built out of that file's content headers, and it's available for you to use as the {{ TOCTREE }} template variable. no cap.

the tree is made of lists of links for the headers, and you'd usually drop it right before the content, like an index. main character placement, honestly 👑

✨ USAGE ✨

say your source file has this content:

TITLE: Some Title
-----------------
# Header 1

Some content.

## Header 2

More content.

### Header 3

Content.

and a template block has this content:

{% block entry %}
{{ TOCTREE }}
{% endblock %}

then the output would be similar to this:

<ul>
    <li><a href="#header-1">Header 1</a></li>
    <ul>
        <li><a href="#header-2">Header 2</a></li>
        <ul>
            <li><a href="#header-3">Header 3</a></li>
        </ul>
    </ul>
</ul>

look at that nesting. it's giving organized. 🎀

🧚 controlling the depth (the TOCTREE_MAXDEPTH variable)

the depth of the tree can be controlled using the TOCTREE_MAXDEPTH variable. you can define it globally (peep blogc(1)) or for each source file (peep blogc-source(7)). iykyk.

  • set it to 0 → the generator is disabled. no tree, no vibes. 🙈
  • set it to a positive number → that limits the number of tree levels to that value.
  • the default value is -1 → which means no maximum depth.
⚠️ important bestie: the depth is evaluated from the lower header level available in the content. so if a source file only has level 2 and level 3 headers, and TOCTREE_MAXDEPTH=1, only the headers with level 2 make it into the "table of contents" tree. the counting starts from what you actually have, not from level 1. periodt.

🌈 example time

for a source file with the following content:

TITLE: Some Title
TOCTREE_MAXDEPTH: 1
-----------------
## Header 2

Some content

### Header 3

More content

with the same template presented before, it would generate output similar to this:

<ul>
    <li><a href="#header-2">Header 2</a></li>
</ul>

see how Header 3 got left out? that's the depth limit doing its thing. slay 💅

💀 BUGS 💀

please report any issues to: https://github.com/blogc/blogc

(not me begging you to file an issue... but like, do it 🫶)

👑 AUTHOR 👑

Rafael G. Martins <rafael@rafaelmartins.eng.br>

🌟 SEE ALSO 🌟

okay that's the whole page, you're officially a toctree expert, bestie. this was written by Rafael G. Martins, from January 2025, as part of the blogc Manual — mwah, go build something iconic 🌸🦋💖

📦 where this page comes from