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

   1 +++
   2 title = "Hacking BookStack"
   3 description = "Performing deeper customisation & extending the platform to suit your needs"
   4 date = "2020-02-02"
   5 type = "admin-doc"
   6 +++
   7
   8 Sometimes you may want to perform deeper customisation to BookStack or extend the system to suit your use-case. The core of BookStack is fairly rigid as it's intended to be a configured, ready-to-use system out of the box but there are a few advanced options for performing more advanced modifications without needing to alter the system code-base.
   9
  10 _**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.**_
  11
  12 ---
  13
  14
  15 ### BookStack API
  16
  17 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.
  18
  19 **Reference Links**
  20
  21 - [API documentation of our demo instance](https://demo.bookstackapp.com/api/docs).
  22 - [Our "BookStack API Scripts" repo containing examples](https://github.com/BookStackApp/api-scripts).
  23
  24 ---
  25
  26 ### Custom HTML Head Option
  27
  28 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.
  29
  30 ---
  31
  32 ### BookStack Editor Events
  33
  34 For the core underlying libraries, used in the BookStack page editors, we emit some custom events as part of their lifecycle.
  35 You can listen for these events to hook in and alter their configs or to gain a reference to the underlying editor instance.
  36 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:
  37
  38 ```html
  39 <script>
  40         // TinyMCE WYSIWYG editor events
  41         window.addEventListener('editor-tinymce::pre-init', event => console.log('TINYMCE-PRE_INIT', event.detail));
  42         window.addEventListener('editor-tinymce::setup', event => console.log('TINYMCE-SETUP', event.detail));
  43
  44         // CodeMirror / Markdown-it Markdown editor events
  45         window.addEventListener('editor-markdown-cm::pre-init', event => console.log('MARKDOWN-CODEMIRROR-PRE_INIT', event.detail));
  46         window.addEventListener('editor-markdown::setup', event => console.log('MARKDOWN-EDITOR-SETUP', event.detail));
  47
  48         // Diagrams.net configure event
  49         // Reference: https://www.diagrams.net/doc/faq/configure-diagram-editor
  50         // If using a custom diagrams.net instance, via the `DRAWIO` option, you will need to ensure
  51         // this your URL has the `configure=1` query parameter.
  52         window.addEventListener('editor-drawio::configure', event => console.log('DIAGRAMS.NET-CONFIGURE', event.detail));
  53 </script>
  54 ```
  55
  56 ---
  57
  58 ### Visual Theme System
  59
  60 BookStack allows visual customization via the theme system which enables you to extensively customize views, translation text & icons.
  61 Documentation for this system is contained within [the project repo here](https://github.com/BookStackApp/BookStack/blob/development/dev/docs/visual-theme-system.md).
  62
  63 _**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.**_
  64
  65
  66 ---
  67
  68 ### Logical Theme System
  69
  70 BookStack allows PHP code-based extension via what we call the "Logical Theme System".
  71 This works by hooking into specific events where you can then perform custom actions or extension of the underlying framework.
  72 Documentation for this system is contained within [the project repo here](https://github.com/BookStackApp/BookStack/blob/development/dev/docs/logical-theme-system.md).
  73
  74 _**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.**_