Last updated:
2020-10-25 11:57

Purpose: This document explains how to render an HTML sitemap in your Firn layouts.

Prerequistes: an understanding of The Render Function, layouts. The sitemap is also related to breadcrumbs.


The sitemap is a list of all the org-files as they appear on your site. It can be rendered as an HTML list, and is configurable. The sitemap on this document is rendered as such.

The sitemap is effectively a tree of information. This is possible because files can be "filed under" other files, thus creating a heirarchy and means of organizing files. For example, this file is "filed under" "The Render Function". We use the #+FIRN_UNDER keyword in our frontmatter to denote this key-value pair.

If you were to create a site in which no files are nested under other files (ie, no documents use the +FIRN_UNDER front matter), the sitemap would be a a flat list of links.


Simple usage:

(render :sitemap)

By default, the sitemap will render without being sorted in any manner.

"Limiting" the site map.

Similar to the table of contents, it is possible to render the sitemap starting at a sepcific file "parent". This is useful, for example, if you group a handful of documents under a specific topic, such as "Projects", which then allows you to render a list of links to all projects:

(render :sitemap {:start-at ["Content"]})

; If you want to start further "down the tree", add successive items to the
; start-at vector:

(render :sitemap {:start-at ["Content" "The Render Function"]})

; similarly, you can limit to which depth you would like to render site map nodes.
(render :sitemap {:start-at ["Content"] :depth 1})

Sorting entries

It is possible to sort the entries of the sitemap by various criteria. Sorting as such relies on other data being present in front matter (Dates, ordering). Any files missing the sort criteria will be automatically pushed to the end of the site map list.

By Date

Sorting documents by newest or oldest requires that each file have a +DATE_CREATED front matter.

(render :sitemap {:sort-by :oldest})
; or
(render :sitemap {:sort-by :newest})

By Pre-determined Order

You may also sort by an arbitrary "order" denoted by the usage of the #+FIRN_ORDER front matter. A document with a "FIRN_ORDER" value of 1 will come before a document with a value of 2.

(render :sitemap {:sort-by :firn-order})

Usage of the FIRN_ORDER front matter is also relevant to use of the adjacent files renderer.


(render :sitemap {:sort-by :alphabetical})
Previous: Folding Next: Adjacent Files