Configuration

Last updated:
2020-09-23 18:45

Overview

Like many other static site generators, Firn can be configured. Configuration happens in the config.edn file at the root of the Firn site that is generated when you run firn new from the command line.

When you build or serve your site using the Firn CLI, this file is read into memory and its values are made available to the functions that compile your site. You can inspect the configuration API of this file at the bottom of this document.

Overriding configuration

Any property that begins with :firn-* is a field that will impact the rendering of your files. Specifically, these values correspond to what are known as in-buffer settings in org-mode. Any of these fields in your configuration can be overridden in a single file's in-buffer settings. For example, in your config, you might turn off property rendering:

{;...
 :firn-properties? false
 ;...
 }

This ensures that no property-drawers are rendered under their respective headlines. However, you may have a single file that you want to render the property drawers for, when relevant. At the top of the file in question, you would override this setting by adding this in-buffer setting:

#+FIRN_PROPERTIES?: true

NOTE: in-buffer settings for Firn must be at the top of the file, must be in all capitals, use underscores where hyphens are used in your config, and the values must properly map to a Clojure value. The following in-buffer settings are incorrect:

,#+FIRN-PROPERTIES?: true ; should use an underscore

,#+FIRN_PROPERTIES?: True ; "True" is not a valid clojure value

,#+FIRN_PROPERTIES?: t ; "t" is not a valid clojure value

,#+firn_properties?: t ; "t" is not valid, and firn_properties? should be ; upper cased.

Usage

Most values in config.edn are simple, scalar values - integers, strings, etc. For the sake of clarity, this section will go over settings that have compound values and the usage of which are not immediately clear.

Table of Contents

The firn table of contents is rendered in a layout. If you use the default layout in Firn, it will be at the top of the file. See layouts for more information. :firn-toc is configured as a map with possible values of depth, headline, and exclusive?

{:depth 3          ; render only headlines that are of level 3 and below in the table of contents.
 :headline "Notes" ; The table of contents will begin at the headline "Notes"
 :exclude-headline? true  ; Do not render the headline "Notes", just its children.
}

Referencereference

config.edn

KeyTypePurpose
:dir-datastringorg-attachments/files to get copied into _site.
:enable-rss?booleanIf true, creates a feed.xml in _site.
:firn-properties?booleanFiles: whether to render properties under all headings
:firn-tocmapFiles: settings for any rendered table of contents.
:firn-foldmapRenders folded headlines. Ex: {2 true} - all level 2 headlines will be folded.
:ignored-dirsvectorDirs of org files to ignore at build time.
:site-descstringThe description of your site, used for RSS.
:site-titlestringThe title of your site, used for RSS.
:site-urlstringThe root url of your site.
:run-build-clean?stringWhether to clean out unused attachments on build. Values: "never" / "always" / "prompt"