Front Matter

Last updated:
2020-09-25 19:04

Overview

To use Firn, you will need to add some "Front Matter" to your org-files. Front Matter is common in many static-site-generators. Firn uses org-mode in-buffer-settings to set Front Matter.

Currently, Firn requires that each file it processes at least have a #+TITLE: front-matter key value.

Firn Front Matter

The following front-matter are processed by Firn and/or made available to layouts for processing.

KeyTypePurpose
#+TITLE:stringRequired: Used in site-map, links, etc
#+DATE_CREATEDorg-mode-dateFile date created
#+DATE_UPDATEDorg-mode-dateFile last updated
#+FIRN_TAGSlistCreates file based tags.
#+FIRN_PROPERTIES?booleanWhether to render properties under all headings
#+FIRN_TOCmapSettings for any rendered table of contents
#+FIRN_FOLDmapFold headings of a specified level: ex: {3 true 4 true}
#+FIRN_ORDERintegerEnables sorting files in the site-map
#+FIRN_PRIVATEbooleanWhether or not to read the file in question
#+FIRN_SITEMAP?booleanWhether to include the file in the site-map.
#+FIRN_UNDERlistCategories for which the documents falls under

Changing some of these values from file to file will result in your files being rendered differently. Meanwhile, you can set the default values for certain front-matter in your config.edn file, as detailed in the configuration document.

Let's consider an example - we will enable headline folding in a document.

#+FIRN_FOLD {1 true 2 true}

The above will result in all level 3 and 4 headings being folded. If you would like to render a certain file so that all level 1 headings (and no others) are folded, you could do by overriding the :firn-fold value in your config in your front matter by setting #+FIRN_FOLD: {1 true}

In this case, FIRN_FOLD actually takes a clojure value (in this case, a map) that is evaluated when your site is built.

Custom Front Matteradvanced

All front matter will be accessible as metadata when it comes time to render your layouts. That is to say, you can create your own custom keywords in your files, and use them in your layouts. To access your front-matter, you will have to dig into the data structure of your "file" in your layout. These keywords are not read in as Clojure values - they will be available just as strings.

(defn project
  [{:keys [meta]}]
  (let [my-keywords (-> meta :keywords)]
    [:html [:body (str my-keywords)]]))