Tags (Documentation)

Uriel can optionally build a tag index, to add additional ways to link pages together.

The basic idea is that you add one or more tags to various nodes throughout your site, and Uriel can build a tag index, with individual tag pages that link back to the nodes matching each tag.

In order to set up tags on your site, you need to take the following steps:

Create a Designated Tag Node

Create a designated node that will serve as the root of the tag index. The suggested location is to create this file at nodes/tag. The reason for this is because Uriel will create an additional virtual node for every tag on the site immediately under this path. This way you will end up with individual tag URLs like /tag/foo/ later.

The tag node should, at minimum, include the {{tag-list:*}} somewhere on the page. This parameter will be expanded out to contain links to all of the individual generated tag pages.

It can also be helpful to set the Link-Prefix / Link-Suffix headers to control the formatting for the list of tag links.

The tag node for this documentation site can be found here.

Set the Tag-Node Header on the Root Node

Uriel doesn't make any assumptions about where you put the tag node. You have to specify which node to use. The way that you do this is by adding a header to the root node to indicate which node Uriel should use as the basis for the tag hierarchy it's going to create.

The way that you designate which node is the tag node, is by setting the Tag-Node header on the root node.

If you used the recommended path of nodes/tag for the tag node, then you just need to add the following header to the root node:

Tag-Node: tag

In this case, tag refers to the node defined in the nodes/tag file.

Add Tags to Other Nodes

Now that the tag node is all set up, the final step is to add tags to other nodes.

Setting up the tag node is something you only need to do once. Adding tags to nodes is something that you will probably continue to do as long as you are updating your site.

To add one or more tags to a node, simply add a Tags header to each node, with a comma-separated list of tags.

This page has two different tags, foo and bar. The Tags header for this node looks like this:

Tags: foo, bar

Adding these tags to this node causes several things to happen:

• Each tag added to this node causes a tag page to be created, if it doesn't already exist.
• A link to this node is added to each tag page

For example, by adding the foo and bar tags to this node, the /tag/foo/ and /tag/bar/ pages come into existence, and link back to this page.

Add Links to Tags

You will probably want to add links from each node to the tag pages that it is associated with. The easiest way to do this automatically is to set this up once in a template.

Add the following code snippet to a template, where it will be displayed on pages of your web site that have tags:

{{node-link:tag}}: {{tag-list:*}}

This is what the code above evaluates to on this node:

Tags: bar, foo

The {{node-link:tag}} substitution parameter links to the tag node, and uses the Title header of that page for the link text. On this documentation site, the tag node has its title set to Tags, which is what you see in the link here.

The {{tag-list:*}} substitution parameter in this case links to the tags that are defined on the current node.

Tags: bar, foo