Firn Tags

Last updated:
2020-10-16 15:35

Purpose: This document explains how to organize your documents with "Firn tags" (file-based tagging) as well as how to render a list of tags on a Firn site.

Prerequistes: an understanding of The Render Function, layouts and front matter.

Overview

Firn can tag files using the front matter #+FIRN_TAGS or #+ROAM_TAGS. Firn tags are for categorizing information on a file to file basis. Please note this is different from using org-mode tags (referred to as "org-tags" throughout this documentation.)

Move on to learn how you might use these tags.

Usage

Firn's file tagging functionality is partially based on how Org Roam handles tagging. Tag values are space delimited. Multi-word tags must be wrapped in quotations marks.

Example

An example usage might be to tag this file you are reading as such:

#+TITLE: "Firn Tags"
#+FIRN_TAGS: Taxonomy Organization "Information Architecture"

The above will create three tags: Taxonomy, Organization and Information Architecture.

Rendering Tags in your Layouts

When it comes time to render your list of accumulated tags and their respectively tagged files you may do one of the following:

Render ALL tags across your Firn site.

This is useful for displaying your entire site's set of tags. It will create a list of lists, where the parent list is the tag name, and it's children are all the files that are make use of that tag.

(render :firn-tags)

;; It is possible to sort your tags by :alphabetical | :newest | :oldest
(render :firn-tags {:sort-by :alphabetical})

Render the list of tags for a specific file.

It is common to list the tags that a file has on the rendered output of that file.

If you are using tags, it is likely that you would want each file to display what tags it may have. These tags are then clickable; clicking on a tag will take you to your firn-tags-path - a web path that you designate in your config.edn. For specific details on how to set up a tags page, view "set up a tags file" on the org-tags page.

(render :firn-file-tags)

Using Org Roam's Tagging

Firn automatically reads in the ROAM_TAGS front matter, allowing you to make use of whatever tags you might already have if you are an org-roam user. If you have both FIRN_TAGS and ROAM_TAGS in your front-matter, FIRN_TAGS will be given precedence for providing the tag values for a file when building your site.

Previous: Org Tags Next: Table Of Contents