Tags

Add a tag to a page

Add tags to a page by adding tags in the frontmatter with values inside brackets, like this:

---
title: 5.0 Release Notes
permalink: /doc/en/contrib/release_notes_5_0.html
tags: [formatting, single_sourcing]
---

Tags overview

To prevent tags from getting out of control and inconsistent, first make sure the tag appears in the _data/tags.yml file. If it’s not there, the tag you add to a page won’t be read. This helps to ensure that you use tags consistently and don’t add new tags without the corresponding tag archive pages.

Additionally, you must create a tag archive page similar to the other pages named tag_{tagname}.html in the tags folder. This theme doesn’t auto-create tag archive pages.

For simplicity, make all your tags single words (connect them with hyphens if necessary).

Setting up tags

Tags have a few components.

1. In the _data/tags.yml file, add the tag names you want to allow. For example:

   allowed-tags:
     - getting_started
     - overview
     - formatting
     - publishing
     - single_sourcing
     - special_layouts
     - content types
   

2. Create a tag archive file in the tags folder for each tag in your tags_doc.yml list. Name the file following this pattern: tag_collaboration.html.

   Each tag archive file needs only this:

   ---
   title: "Collaboration pages"
   tagName: collaboration
   search: exclude
   permalink: /doc/en/contrib/tag_collaboration.html
   sidebar: contrib_sidebar
   ---
   {% include taglogic.html %}
   

   Note: In the _includes/mydoc folder, there’s a taglogic.html file. This file (included in each tag archive file) has common logic for getting the tags and listing out the pages containing the tag in a table with summaries or truncated excerpts. You don’t have to do anything with the file — just leave it there because the tag archive pages reference it.

</div>

1. Change the title, tagName, and permalink values to be specific to the tag name you just created.

   By default, the _layouts/page.html file will look for any tags on a page and insert them at the bottom of the page using this code:

<div class="tags">
{% if page.tags != null %}
<b>Tags: </b>
{% assign projectTags = site.data.tags.allowed-tags %}
{% for tag in page.tags %}
{% if projectTags contains tag %}
<a href="{{ "tag_" | append: tag | append: ".html" }}" class="btn btn-default navbar-btn cursorNorm" role="button">{{page.tagName}}{{tag}}</a>
{% endif %}
{% endfor %}
{% endif %}
</div>

Because this code appears on the _layouts/page.html file by default, you don’t need to do anything in your page to get the tags to appear. However, if you want to alter the placement or change the button color, you can do so within the _includes/taglogic.html file.

You can change the button color by changing the class on the button from btn-info to one of the other button classes bootstrap provides. See [Labels][labels.html for more options on button class names.

Retrieving pages for a specific tag

If you want to retrieve pages outside of a particular tag_archive page, you could use this code:

navigation pages:
<ul>
{% for page in site.pages %}
{% for tag in page.tags %}
{% if tag == "navigation" %}
<li><a href="{{page.permalink}}">{{page.title}}</a></li>
{% endif %}
{% endfor %}
{% endfor %}
</ul>

Here’s how that code renders:

navigation pages:

Empty tags?

If your page shows “tags:” at the bottom without any value, it could mean a couple of things:

• You’re using a tag that isn’t specified in your allowed tags list in your tags.yml file.
• You have an empty tags: [] property in your frontmatter.

If you don’t want tags to appear at all on your page, remove the tags property from your frontmatter.

Remembering the right tags

Since you may have many tags and find it difficult to remember what tags are allowed, I recommend creating a template that prepopulates all your frontmatter with all possible tags. Then just remove the tags that don’t apply.