draft = false
+++
-TODO - Update docs
-
For July we have what could be considered a "stepping-stone" release since it marks the start of some underlying
permission system changes while bundling in a rich set of system enhancements & minor features. Let's jump right in.
This can then allow very easy content-level customization through the use of tags, with only the addition of some custom CSS in the "Custom HTML Head Content" setting. For example, you could apply a `Layout: dual` tag, only with some `.tag-pair-layout-dual .page-content p {columns: 2}` rule to make paragraphs dual-column on those tagged pages.
-TODO - Link to docs below
-
-Some normalisation is applied to generate the classes but see our docs section about this for full details and considerations using this advanced customization feature.
+Some normalization is applied to generate the classes. See our [docs section about tag classes](/docs/admin/hacking-bookstack/#tag-classes) for full details.
### New "Activity Logged" Logical Theme System Event
Within the settings area you'll find a 'Custom HTML head content' setting. You can use this to add in any custom JavaScript or CSS content which enables you to override default BookStack functionality and styles.
+
+---
+
+### Visual Theme System
+
+BookStack allows visual customization via the theme system which enables you to extensively customize views, translation text & icons.
+Documentation for this system is contained within [the project repo here](https://github.com/BookStackApp/BookStack/blob/development/dev/docs/visual-theme-system.md).
+
+_**Note: The files that can be override using the theme system are not deemed to be stable. BookStack core files may change on any release causing changes in behaviour to your overrides. Theme overrides are not officially supported in any way.**_
+
+
+---
+
+### Logical Theme System
+
+BookStack allows PHP code-based extension via what we call the "Logical Theme System".
+This works by hooking into specific events where you can then perform custom actions or extension of the underlying framework.
+Documentation for this system is contained within [the project repo here](https://github.com/BookStackApp/BookStack/blob/development/dev/docs/logical-theme-system.md).
+
+_**Note: Only the API described in the logical-theme-system document is considered stable & supported. Any usage of other application classes is regarded as unstable and unsupported.**_
+
---
### BookStack Editor Events
---
-### Visual Theme System
+### Tag Classes
-BookStack allows visual customization via the theme system which enables you to extensively customize views, translation text & icons.
-Documentation for this system is contained within [the project repo here](https://github.com/BookStackApp/BookStack/blob/development/dev/docs/visual-theme-system.md).
+While primarily for categorization, tags within BookStack can also provide opportunities for customization.
+When viewing an item with tags applied, those tags will be normalized to CSS classes and applied to the `<body>` element of the page. As an example, a tag name/value pair of `Priority: Critical` will apply the following classes to the body:
-_**Note: The files that can be override using the theme system are not deemed to be stable. BookStack core files may change on any release causing changes in behaviour to your overrides. Theme overrides are not officially supported in any way.**_
+- tag-name-priority
+- tag-value-critical
+- tag-pair-priority-critical
+For the normalization to classes, the following is done to both the name and value of the tag:
----
+- Text is lower-cased
+- Spaces and hyphens are stripped
-### Logical Theme System
+This normalization provides relatively stable class naming for CSS targeting, but note it does mean that two tags, of different values, could be normalized to the same CSS class names in some scenarios.
-BookStack allows PHP code-based extension via what we call the "Logical Theme System".
-This works by hooking into specific events where you can then perform custom actions or extension of the underlying framework.
-Documentation for this system is contained within [the project repo here](https://github.com/BookStackApp/BookStack/blob/development/dev/docs/logical-theme-system.md).
+As an example of usage, pages with the tag `Priority: Critical` could have their text made red with the following "Custom HTML Head Content" setting value:
-_**Note: Only the API described in the logical-theme-system document is considered stable & supported. Any usage of other application classes is regarded as unstable and unsupported.**_
\ No newline at end of file
+```html
+<style>
+.tag-pair-priority-critical .page-content { color: red; }
+</style>
+```
\ No newline at end of file
* [Revision Limit](#revision-limit)
* [Custom User Avatar Fetching](#custom-user-avatar-fetching)
* [Custom diagrams.net URL](#custom-diagramsnet-url)
+* [IP Address Storage Precision](#ip-address-storage-precision)
---
Refer to this diagrams.net guide to see what options are supported: [diagrams.net embed URL parameters](https://www.diagrams.net/doc/faq/supported-url-parameters). In particular, the `stealth=1` option might be of interest if you
don't want other external services to be used.
+
+---
+
+### IP Address Storage Precision
+
+Some areas of BookStack, such as the activity audit log, store and show IP address of users.
+By default, the entire IP address will be stored but you can adjust with the following `.env` option:
+
+```bash
+# Alter the precision of IP addresses stored by BookStack.
+# Should be a number between 0 and 4, where 4 retains the full IP address
+# and 0 completely hides the IP address. As an example, a value of 2 for the
+# IP address '146.191.42.4' would result in '146.191.x.x' being logged.
+# For the IPv6 address '2001:db8:85a3:8d3:1319:8a2e:370:7348' this would result as:
+# '2001:db8:85a3:8d3:x:x:x:x'
+IP_ADDRESS_PRECISION=2
+```
\ No newline at end of file
projects / website / commitdiff