This extension enables the tag filter feature by using the page’s kind property to add multiple routes, such as http://127.0.0.1/blog/tag/:tag/1, to each page to allow users to list all pages in the current folder by tag.

Panel extension can help you to automate everything. But if you have to, you can still make this extension work without the GUI feature. Before we start, you need to know how this extension works.

Writing a tag file is the same as writing a page file. The only difference is that you have to write the id property separately from the page. Be sure to specify a unique number for each id.data file. These numbers will then be used to associate the tag file with the kind property on each page:

.\
└── lot\
    ├── page\
    │   └── …
    └── tag\
        ├── bar\
        │   └── id.data ✔
        ├── baz\
        │   └── id.data ✔
        ├── foo\
        │   └── id.data ✔
        ├── bar.page
        ├── baz.page
        └── foo.page

Here’s an example of what a tag file might contain:

---
title: Tag Name
description: Short description about this tag.
type: Markdown
...

Long description about this tag.

To associate tags with the current page, create a kind.data file in the relevant folder that contains a list of tag IDs written in a valid JSON format:

.\
└── lot\
    ├── page\
    │   ├── lorem-ipsum\
    │   │   └── kind.data ✔
    │   └── lorem-ipsum.page
    └── tag\
        └── …

Example contents of a kind.data file:

[ 1, 2, 3 ]

You can also include the kind property in the page header, but this method may not be performance efficient when reading the data:

---
title: Page Title
description: Page description.
author: Taufik Nurrohman
type: Markdown
kind: [ 1, 2, 3 ]
...

Page content goes here.

Usage

These HTML classes will be added to the root element if it contains a class attribute when you are on the tags page. You can use this feature to create a specific look or response on your site from the client side if the following classes are found in the root element:

is:tags

Will be added if the current items view is a tags view and is not empty.

Example usage in CSS code:

.is\:tags body {
  border-top: 4px solid #f00;
}

Example usage in JS code:

if (document.documentElement.classList.contains('is:tags')) {
    console.info('You are currently in the tags page.');
}

These additional conditional statements are available for use in layouts to show/hide elements on your site from the server side:

$site->is('tags')

Returns true if the current items view is a tags view and is not empty.

Example usage in HTML/PHP code:

<?php if ($site->is('tags')): ?>
  <p role="alert">
    <?= i('You are currently in the tags page.'); ?>
  </p>
<?php endif; ?>

These additional variables are available for use in layouts that carry data related to the currently active tags page:

$tag

This variable is an instance of the Tag class, which you can use to get the current tag information.

Example usage in HTML/PHP code:

<?php if ($site->is('tags') && !empty($tag)): ?>
  <p role="alert">
    <?= i('Showing pages filtered by tag %s.', $tag->title); ?>
  </p>
<?php endif; ?>

This extension will also add query and tags properties to the page only if the page contains a kind property that is not empty:

// These numbers refer to the tag IDs.
$kind = $page->kind; // Returns `[1, 2, 3]`
// These queries are automatically generated based on the available tags.
// They may be generated less than the amount of `kind` data because non-existent tag IDs are ignored.
$query = $page->query; // Returns `['bar', 'baz', 'foo']`
// These tags data are also generated based on the available tags.
$tags = $page->tags; // Returns `Tags` class instance

Example usage in HTML/PHP code:

<?php if ($tags = $page->tags): ?>
  <?php if ($tags->count): ?>
    <ul>
      <?php foreach ($tags as $tag): ?>
        <li>
          <a href="<?= eat($tag->link); ?>" rel="tag" title="<?= eat($tag->description); ?>">
            <?= $tag->title; ?>
          </a>
        </li>
      <?php endforeach; ?>
    </ul>
  <?php else: ?>
    <p role="status">
      <?= i('This page does not contain any %s.', 'tags'); ?>
    </p>
  <?php endif; ?>
<?php endif; ?>