Custom Pages

Last updated:
2020-09-23 18:39

Overview

Similar to layouts, on creating a Firn site, you will find a folder: _firn/pages. This folder enables users to create custom pages that are converted from the template language (hiccup) into HTML. This is useful if you want to create a page that does not render any org-mode content.

Tags - an out of the box page

Creating a new Firn site comes with a custom page: tags.clj. This file exists to provide an example of a custom page, as well as to give user's an out-of-the-box solution for displaying org-tags with Firn. When Firn processes your org-mode files, it collects all heading tags, and stores them in a Clojure vector (simply, a list). A user may access this list of tags directly, as they are made available to layouts and pages, or the list of tags can be rendered using a pre-set render function.

You can of course delete this file if you do not want to render tags.

Limitations

"Pages" are not based around interpreting and constructing content from org-mode files. So, use of the (render) function is limited to performing renderings of site-wide content, such as the site-map (whereas rendering say, breadcrumbs, or an org-mode heading will not work.)

Metadata

Custom pages will not be displayed in the site-map. Site-map metadata, such as the firn-order, or firn-under values enable the sorting and grouping of your site-map as you like. This data is gathered from org-mode keywords. Because custom pages in the /pages directory do not have this metadata available, they are rendered with a pre-configured set of metadata as so:

Flat routinglimitation

Currently, Firn only supports creating custom pages at the root level of/pages - unlike org-mode files, if you have a directory within the /pages directory, it will not translate to a nested url. For example, if you have the file /pages/my-category/my-custom-page-1.clj - it will be translated into an html file named my-custom-page-1.html at the root of your site url.