Extension · Mecha CMS

Add extra functionality to the core engine.


Author: Taufik Nurrohman · 1364 Views


Page tags.

Download Version 1.5.0 Download Development Version

This extension enables tags feature on any pages by utilizing the kind property value as the tag ID. This extension also adds a new route definition like https://mecha-cms.com/blog/tag/slug on every pages to make it possible to list all pages in the current folder by tags.


This extension automatically adds a tag folder within the lot folder, which will also automatically set a new constant based on the folder name with a value of the folder path:



There are some methods added to the default classes:


Get::tags($folder = TAG, …, $sort = [1, 'id'], …);

Arguments are the same with Get::pages(), except the $folder parameter that uses TAG constant value by default, and the $sort parameter that uses id as the default sort key instead of time.


From::tag($slug, $fail = false);

Get tag ID from the tag slug.


To::tag($id, $fail = false);

Get tag slug from the tag ID.

Working with Tags 

Panel extension can help you to automate everything from the start. But, if you have to, you can still make this extension works without any backend extensions at all. It is because the panel extension was created only to convert your generic files and folders interface into a rich graphical user interface. Just like a comparison between Command Prompt appearance to the desktop Windows appearance.

Before we get started, you need to understand about the way this extension works.

Page Properties 

First, you have to know that this extension adds a query and tags property to the page if the page contains kind property that is not empty:

$page = [
    'kind' => [1, 2, 3], // [^1]
    'query' => ['foo', 'bar', 'baz'], // [^2]
    'tags' => [ // [^3]
        'foo' => [
            'id' => 1,
            'slug' => 'foo',
            'url' => 'https://mecha-cms.com/tag/foo'
        'bar' => [
            'id' => 2,
            'slug' => 'bar',
            'url' => 'https://mecha-cms.com/tag/bar'
        'baz' => [
            'id' => 3,
            'slug' => 'baz',
            'url' => 'https://mecha-cms.com/tag/baz'

// [^1]: These numbers will be used as the tag ID.
// [^2]: These queries are generated automatically based on the available tags.
// [^3]: These rich tags data are also generated based on the available tags.

File Structure 

Second, writing tag files is the same as writing regular page files. The only difference is that the id property must be stored in a separated file, not embedded in the page file content.

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

File Content 

Third, make sure to set a unique integer number on each id.data files. These numbers, then will be used to connect between the kind data with the available tags.

Here’s an example of a tag file content:

title: Tag Name
description: Short description about this tag.

Long description about this tag.


Fourth, to connect between tags and the current page, create a kind.data file in the related folder, contains list of tags ID written in a valid JSON format:

 └── page\
     ├── test-page\
     │   └── kind.data
     └── test-page.page

Example content of kind.data file:


You can also embed the kind property to the page header, but this way is a little bit slower to be parsed than the separated file version:

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

Page content goes here.

Tags Listing 

echo implode(', ', $page->query);
$tags = [];
foreach ((array) $page->tags as $v) {
    $tags[] = HTML::a($v->title, $v->url);
echo implode(', ', $tags);


  • $site->tag → Return the current page tag when you are in the tags page. Default is null.


  • tag.* → Behaves like page.* hooks, but its target is only for the rich tags output.