Tag Values in Page Content via Includes

• Author: @ssddanbrown
• Created: 16th Aug 2025
• Updated: 16th Aug 2025
• Last Tested On: v25.07.1

This hack allows you to dynamically pull in the value of tags into page content, via customizing how page include tags are parsed. This hack will attempt to use tags on the page itself, then look to the parent chapter (if existing), then the parent book’s tags.

Usage

Within page content, insert an include tag with the following specific format:

1

{{@0tag:<tag-name>}}

Replacing <tag-name> with the name of your intended tag. The tag lookup is performed case-insensitive, so don’t worry about correct casing. The hack will then replace the include tag with the value of any relevant tags found, or otherwise blank out the include tag.

As an example, if I had a tag with name Color and value Blue, I’d use the include tag {{@0tag:color}} which will be replaced with Blue (using the tag value) when the page is shown.

Considerations

• This is subject to many of the same limitations as page includes, so the values won’t show in things like preview snippets.
• This implementation does not consider permissions/access to parent chapter/book for tag values, so values may be used from chapters/books which the user does not have access to view.
• Tag name matching is case-insensitive.

Code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

<?php

use BookStack\Entities\Models\Page;
use BookStack\Facades\Theme;
use BookStack\Theming\ThemeEvents;

// Listen to page include parsing events
Theme::listen(ThemeEvents::PAGE_INCLUDE_PARSE, function (string $tagReference, string $replacementHTML, Page $currentPage, ?Page $referencedPage) {

    // Allow default behaviour for non-tag-based includes
    if (!str_starts_with($tagReference, '0tag:')) {
         return null;
    }

    // Get the target tag name from the include reference
    $tagName = explode(':', $tagReference)[1];

    // Fetch the tag value from the page, parent chapter, or parent book
    $tagValue = $currentPage->tags()->where('name', '=', $tagName)->first()?->value ??
                $currentPage->chapter?->tags()->where('name', '=', $tagName)->first()?->value ??
                $currentPage->book?->tags()->where('name', '=', $tagName)->first()?->value ?? '';

    // Return the tag value to be used for the include
    return $tagValue;
});