Org Tags

Last updated:
2020-09-25 19:07

Purpose: This document explains how to organize your headlines with org-tags as well as how to render a list of org-tags on a Firn site.

Prerequistes: an understanding of The Render Function and firn configuration.

Overview

Firn collects org-tags when it parses your org-mode files and are accessible in your layouts through the render function or as raw data.

Usage

Continue using org-mode tags as you normally would. When it comes time to display your tags you need to do two things.

  1. Setup a tag file

  2. Render your org-tags.

Setup a tag file

All org tags are html links that must link somewhere. Clicking on an org-tag should link to a "tag file" which displays all org-tags as they have been collected during the Firn build process. By default, creating a new firn site with the firn new commands will generate the file _firn/pages/tags.clj . This is where your org-tags will be displayed.

You can rename this file to whatever you want, so long as it can be linked to as a valid url link.

If you do choose to change the name of your tag file, make sure you alter the :org-tags-path value in your config.edn - this ensures that every tag that displays next to an org-mode heading links to the proper url.

Render org-tags

Once you have setup your tag file, you need to render your org tags:

(render :org-tags)

Done!

The org-tags data structure

A map of org tags is available in your layouts under the keyword "org-tags". This is useful if you want complete control of how your tags are rendered to page.

The tag data is a map that looks roughly as follows:

{"FAQ"           [{:from-headline "FAQ",
                   :headline-link "http://localhost:4000/index#faq",
                   :from-file     "Home",
                   :from-url      "http://localhost:4000/index",
                   :tag-value     "FAQ"}
                  {:from-headline "How do I customize the styling of my layouts?",
                   :headline-link "http://localhost:4000/styling#how-do-i-customize-the-styling-of-my-layouts?",
                   :from-file     "Styling",
                   :from-url      "http://localhost:4000/styling",
                   :tag-value     "FAQ"}],
 "advanced"      [{:from-headline "Custom Front Matter",
                   :headline-link "http://localhost:4000/front-matter#custom-front-matter",
                   :from-file     "Front Matter",
                   :from-url      "http://localhost:4000/front-matter",
                   :tag-value     "advanced"}],
 "attachments"   [{:from-headline "Adding attachments",
                   :headline-link "http://localhost:4000/tutorial#adding-attachments",
                   :from-file     "Step by Step Tutorial",
                   :from-url      "http://localhost:4000/tutorial",
                   :tag-value     "attachments"}
                  {:from-headline "Attachments",
                   :headline-link "http://localhost:4000/limitations#attachments",
                   :from-file     "Limitations",
                   :from-url      "http://localhost:4000/limitations",
                   :tag-value     "attachments"}],
 "configuration" [{:from-headline "Understanding config.edn",
                   :headline-link "http://localhost:4000/tutorial#understanding-configedn",
                   :from-file     "Step by Step Tutorial",
                   :from-url      "http://localhost:4000/tutorial",
                   :tag-value     "configuration"}],
 "emacs"         [{:from-headline "A note on Emacs",
                   :headline-link "http://localhost:4000/tutorial#a-note-on-emacs",
                   :from-file     "Step by Step Tutorial",
                   :from-url      "http://localhost:4000/tutorial",
                   :tag-value     "emacs"}],
 "example"       [{:from-headline "Tags",
                   :headline-link "http://localhost:4000/sample-page#tags",
                   :from-file     "Sample Page",
                   :from-url      "http://localhost:4000/sample-page",
                   :tag-value     "example"}],
 "folding"       [{:from-headline "Rendering folded headlines",
                   :headline-link "http://localhost:4000/the-render-function#rendering-folded-headlines",
                   :from-file     "The Render Function",
                   :from-url      "http://localhost:4000/the-render-function",
                   :tag-value     "folding"}],
 "reference"     [{:from-headline "Reference",
                   :headline-link "http://localhost:4000/configuration#reference",
                   :from-file     "Configuration",
                   :from-url      "http://localhost:4000/configuration",
                   :tag-value     "reference"}]}