BookStack/dev/docs/theme-system-modules.md

Theme System Modules

A theme system module is a collection of customizations using the visual and logical theme systems, provided along with some metadata, that can be installed alongside other modules within a theme. They can effectively be thought of as "plugins" or "extensions" that can be applied in addition to any customizations in the active theme.

Module Location

Modules are contained within a folder themselves, which should be located inside a modules folder within a BookStack theme folder. As an example, starting from the themes/ top-level folder of a BookStack instance:

themes
└── my-theme
    └── modules
        ├── module-a
        │   └── bookstack-module.json
        └── module-b
            └── bookstack-module.json

Module Format

A module exists as a folder in the location as detailed above. The content within the module folder should then follow this format:

• bookstack-module.json - REQUIRED - A JSON file containing the metadata for the module.
• functions.php - OPTIONAL - A PHP file containing code for the logical theme system.
• icons/ - OPTIONAL - A folder containing any icons to use as per the visual theme system.
• lang/ - OPTIONAL - A folder containing any language files to use as per the visual theme system.
• public/ - OPTIONAL - A folder containing any files to expose into public web-space as per the visual theme system.
• views/ - OPTIONAL - A folder containing any view additions or overrides as per the visual theme system.

You can create additional directories/files for your own needs within the module, but ideally name them something unique to prevent conflicts with the above structure.

Module JSON Metadata

Modules are required to have a bookstack-module.json file in the top level directory of the module. This must be a JSON file with the following properties:

• name - string - An (ideally unique) name for the module.
• description - string - A short description of the module.
• version - string - A string version number generally following semantic versioning.
  • Examples: v0.4.0, 4.3.12, v0.1.0-beta4.

Customization Order/Precedence

It's possible that multiple modules may override/customize the same content. Right now, there's no assurance in regard to the order in which modules may be loaded. Generally they will be used/searched in order of their module folder name, but this is not assured and should not be relied upon.

It's also possible that modules customize the same content as the configured theme. In this scenario, the theme takes precedence. Modules are designed to be more portable and instance abstract, whereas the theme folder would typically be specific to the instance. This allows the theme to be used to customize or override module content for the BookStack instance, without altering the module code itself.

Module Best Practices

Here are some general best practices when it comes to creating modules:

• Use a unique name and clear description so the user can understand the purpose of the module.
• Increment the metadata version on change, keeping to semver to indicate compatibility of new versions.
• Where possible, prefer to insert views before/after instead of overriding existing views, to reduce likelihood of conflicts or update troubles.