Content Tags
While BookStack has a hierarchy at the center of the platform to organise content, you can sometimes desire an extra dimension of categorisation for content. Tags in BookStack offer this in a flexible manner, where a tag can represent a category and value across all levels & parts of the hierarchy.
Tag Format
Tags in BookStack have a name, but can also optionally have a value. This allows detailed & categorised levels of tagging where required for a mixed range of use-cases.
For example, you could use a tag named Critical with no value to mark important high priority pages.
Alternatively, if you have a range of priorities, you could use a tag named Priority with a value
of Critical. Using both a name and value here allows you to identify any content with a Priority set, in addition
to allowing identification of just Critical content.
This can also come in useful when you want to use tags for metadata. For example, you may want to record content review
dates, which you could achieve through a Reviewed At tag with value representing the last review date.
Adding & Managing Tags
Tags can be added to any level of the content hierarchy (Shelves, books, chapters & pages). You can apply tags when editing any such item. For shelves, books & chapters, tags are found in a dropdown section on the edit view:
For pages, you can find tags in the sidebar toolbox when in the page editor:
When editing a tag name or value BookStack will show a list of potential existing relevant options to help you quickly fill the input. Suggestions for values will be just those used before for the chosen tag name, rather than all values across all tags.
While editing, you’re also able to re-order & remove tags as desired. Any changes to tags are saved alongside when you save the item they’re applied to.
Tag Display & Overview
When applied, tags are shown in a few areas of BookStack alongside the content they’re applied to:
- In the sidebar or info pane when viewing any tagged item.
- On items listed within search results.
- In API responses for items.
When viewing an item with tags applied, you can click the tag to start a tag search. Clicking the tag name will start a search for all content that also has a tag of that name. Clicking the value will start a search for other content that has that same tag name & value applied.
To view all tags being used, you can access an Tag overview page via the “View Tags” action found on the books or shelves index,
or you can navigate straight to the /tags URL path. Here you’ll see a list of all tag names used across content you have
visibility of, alongside figures detailing their usage counts across each type of content.
You can click the tag name, or item counts, to start a relevant filtered search. Where tag values are used, you can also click the link on the right to access a list of all tag values for that tag name, with a similar breakdown as before.
Tags in the Search Index
When content is indexed for searching in BookStack, tags names & values are considered as part of the search engine, and are even given a boost above normal content. This means you can boost content in search results for specific search terms using tags where needed.
Tag Search Operations
Content can be queried in BookStack by tag name or value. This can be used in many areas of BookStack where searching is made available. As mentioned in the sections above, you can often initiate tag searches via clicking tags or statistics in the tag index. Otherwise you can directly use the following syntax:
- Search by tag name:
- Syntax:
[<name>] - Example:
[Location]
- Syntax:
- Search by tag value:
- Syntax:
[<operator><value>] - Example:
[=London]
- Syntax:
- Search by tag name & value:
- Syntax:
[<name><operator><value>] - Example:
[Location=London]
- Syntax:
The following are valid operators: =, !=, <, >, <=, >=, like.
When using the like operator you can use % symbols in the search value to represent wildcards.
Using this syntax you can get quite inventive. As an example, if you were applying Reviewed At tags with values
in a format like 20240627 (YYYYMMDD) you could search for all content with “Reviewed At” dates before 2024 using:
[Reviewed At<20240101].
See our documentation on searching for more advanced search syntax.
Tags for Customization
Tags can also be handy for customization in a range of ways, even if just to assist as extra metadata or identification points. For example, you could use the logical theme system to run a custom action on page creations, and within that change behaviour or action based upon whether the parent Book has a specific tag.
Additionally, BookStack will convert tags to classes within the HTML templates used when viewing content in BookStack, which can then be used for easy tag-controlled customization & styling. Details of these tag classes can be found in our Hacking BookStack documentation here.