Org Tags
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.
Setup a tag file
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"}]}