Table Of Contents

Last updated:
2020-10-19 07:46

Purpose: This document explains how to render and customize a table of contents in your Firn layouts.

Prerequistes: an understanding of The Render Function and how layouts work.


A table of contents can be included in any layout that is processing an org-file (and thus, table of contents cannot be rendered in a custom page.)

A table of contents will by default render every headline it finds in an org-mode file. This may not be ideal and so it is possible to customize which headlines are rendered, unto what depth, and more.

Configuring your table of contents can happen on a site-wide basis (using config.edn), in your layouts (using the render function), or through front matter. This document will


The table of contents can be complex and customizable. The usage section will cover several examples, the first of which will demonstrate the entire API of the table of contents, and the remainder will be used to provide more specific, simpler examples.

To follow any of the examples below, you will need to be editing a layout file.


(render :toc {:depth 3           ; [ int ]      - headline depth to render until
              :headline "Notes"  ; [ string ]   - headline name to start rendering at
              :exclude-headline? ; [ boolean ]  - whether to include the specified headline
              :list-type :ol     ; [ symbol ]   - render the toc as an ordered list. Can be ":ul / :ol"

Every headline

To render every headline in a layout add the following:

(render :toc)

Render only level N headings.

To render every headline in a layout add the following:

(render :toc {:depth 1})

Render only headings starting at a specific name

Some layouts might specify that only certain headlines be rendered in a document. This is useful for separating private and public content in a document. Example:

(render :toc {:headline "Notes"})

In the above, the table of contents will only items that are children of the "Notes" headline.

If you want to exclude "Notes" and only have its child headlines rendered, do the following:

(render :toc {:headline "Notes", :exclude-headline? true})

Overriding values with front matter

The examples above demonstrate how you would set up a table of contents in alayout. If you need to customize the table of contents on a per-file basis, set the options map as a value to the #+FIRN_TOC front matter at the top of an org file.


#+TITLE: Table Of Contents
#+FIRN_UNDER: Content "The Render Function"
#+FIRN_TOC: {:depth 3 :list-type :ul}
Previous: Firn Tags Next: Logbooks