BookStack Code Mirror - website/blobdiff - content/docs/admin/hacking-bookstack.md

_**Note: Customisation options on this page are not deemed to be stable or officially supported. BookStack core files may change on any release causing changes in behaviour to your hacks.**_

+{{<toc>}}

+

---

+### BookStack Hacks Directory

+

+This website has a directory of available hacks [which can be found here](/hacks/).

+These make use of the [Custom HTML Head Option](#custom-html-head-option), [Visual Theme System](#visual-theme-system) and [Logical Theme System](#logical-theme-system) options listed below.

+

+---

### BookStack API

-_**Note: The API is currently in a limited preview stage to ensure the foundations are correct, It will be expanded upon in future releases.**_

+BookStack has a built-in REST API for external interaction and consumption of your BookStack data. API documentation can be found within your BookStack instance at the `/api/docs` URL path. You'll need to have the 'Access system API' role permission to access the API.

-BookStack has a built-in REST API for external interaction and consumption of your BookStack data. API documentation can be found within your BookStack instance at the `/api/docs` URL path. You'll need to have the 'Access system API' role permission to access the API or view the API documentation page.

+**Reference Links**

+

+- [API documentation of our demo instance](https://demo.bookstackapp.com/api/docs).

+- [Our "BookStack API Scripts" repo containing examples](https://codeberg.org/bookstack/api-scripts).

---

### Custom HTML Head Option

---

### Custom HTML Head Option

-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.

+Within the "Settings > Customization" view within BookStack 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.

+

+You can find examples of custom HTML Head customizations on the [hacks part of this site](/hacks/).

---

-### BookStack Editor Events

+### Visual Theme System

-Both the TinyMCE based WYSIWYG editor and the CodeMirror based Markdown editor emit events as part of their lifecycle. You can listen for these hook in and alter their configs or to gain a reference to the underlying editor instance. The below code sample shows the events available; Log out the `detail` property of events, as per the below example, to understand what is passed with the events:

+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).

-```html

-<script>

- // TinyMCE WYSIWYG editor events

- window.addEventListener('editor-tinymce::pre-init', event => console.log('TINYMCE-PRE_INIT', event.detail));

- window.addEventListener('editor-tinymce::setup', event => console.log('TINYMCE-SETUP', event.detail));

-

- // CodeMirror / Markdown-it Markdown editor events

- window.addEventListener('editor-markdown-cm::pre-init', event => console.log('MARKDOWN-CODEMIRROR-PRE_INIT', event.detail));

- window.addEventListener('editor-markdown::setup', event => console.log('MARKDOWN-EDITOR-SETUP', event.detail));

-</script>

-```

+_**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.**_

+

+You can find examples visual theme system customizations on the [hacks part of this site](/hacks/).

---

-### Theme System

+### Logical Theme System

-_**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.**_

+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).

-The theme system provides additional customisation options for those that are a bit more adventurous. The theme system enables you to selectively override BookStack UI resources without having to alter the original BookStack code. To get started create a new folder in the `themes` folder of your BookStack install. Edit your `.env` file and add the following:

+_**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.**_

-```bash

-# Change the value below to match the name of your created folder

-APP_THEME=<theme_folder_name>

-```

+You can find examples of logical theme system customizations on the [hacks part of this site](/hacks/).

-Files can now be placed in your theme folder to override the following resources:

+---

+

+<a id="bookstack-editor-events" data-info="Anchor here for backwards compatibility of existing links"></a>

-##### View Files

+### BookStack JavaScript Public Events

-Content placed in your `themes/<theme_name>/` folder will override the original view files found in the `resources/views` folder. These files are typically [Laravel Blade](https://laravel.com/docs/6.x/blade) files.

+To allow customization of the JavaScript libraries & components used, BookStack emits events as part of their lifecycle

+so that you can define listeners to hook into these events. These can often be used by adding scripts to the

+[custom HTML head content option](#custom-html-head-option).

-##### Icons

+You can find details and a listing of all events [within the project repo here](https://github.com/BookStackApp/BookStack/blob/development/dev/docs/javascript-public-events.md).

-SVG files placed in a `themes/<theme_name>/icons` folder will override any icons of the same name within `resources/icons`. You'd typically want to follow the format convention of the existing icons, where no XML deceleration is included and no width & height attributes are set, to ensure optimal compatibility.

+---

-##### Text Content

+### Tag Classes

-Folders with PHP translation files placed in a `themes/<theme_name>/lang` folder will override translations defined within the `resources/lang` folder. Custom translations are merged with the original files so you only need to override the select translations you want to override, you don't need to copy the whole original file. Note that you'll need to include the language folder.

+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:

-As an example, Say I wanted to change 'Search' to 'Find'; Within a `themes/<theme_name>/lang/en/common.php` file I'd set the following:

+- tag-name-priority

+- tag-value-critical

+- tag-pair-priority-critical

-```php

-<?php

-return [

- 'search' => 'find',

-];

+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

+

+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.

+

+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:

+

+```html

+<style>

+.tag-pair-priority-critical .page-content { color: red; }

+</style>

+```

+

+---

+

+### Export Classes

+

+When PDF or HTML exports are performed in BookStack, the underlying templates define classes to allow customization of styling in specific scenarios.

+For context, PDF exports are rendered via a conversion from HTML to PDF, so CSS styling can be applied for these but support may depend on the underlying PDF conversion engine.

+The classes are applied to the `<body>` element, and are as follows:

+

+- `export` - All HTML/PDF exports

+- `export-format-pdf` - PDF exports

+- `export-format-html` - HTML exports

+- `export-engine-dompdf` - PDF exports using the default DomPDF rendering engine

+- `export-engine-wkhtml` - PDF exports using the default DomPDF rendering engine

+- `export-engine-command` - PDF exports using the command-based PDF rendering option

+

+As an example usage, you could define the following custom style code to make paragraph text red only in PDF exports created via the default DomPDF renderer:

+

+```html

+<style>

+.export-format-pdf.export-engine-dompdf p { color: red; }

+</style>

```

\ No newline at end of file

```

\ No newline at end of file