Added page-include-tag-value hack

diff --git a/content/page-include-tag-value/functions.php b/content/page-include-tag-value/functions.php
new file mode 100644 (file)
index 0000000..82bfc8e
--- /dev/null
+++ b/content/page-include-tag-value/functions.php
@@ -0,0 +1,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;
+});

diff --git a/content/page-include-tag-value/index.md b/content/page-include-tag-value/index.md
new file mode 100644 (file)
index 0000000..740884b
--- /dev/null
+++ b/content/page-include-tag-value/index.md
@@ -0,0 +1,33 @@
++++
+title = "Tag Values in Page Content via Includes"
+author = "@ssddanbrown"
+date = 2025-08-16T00:00:00Z
+updated = 2025-08-16T00:00:00Z
+tested = "v25.07.1"
++++
+
+This hack allows you to dynamically pull in the value of tags into page content, via customizing how [page include tags](/docs/user/reusing-page-content/#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](/docs/user/reusing-page-content/#include-tags) with the following specific format:
+
+```text
+{{@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
+
+{{<hack file="functions.php" type="logical">}}