Themes: Documented public file serving

diff --git a/dev/docs/logical-theme-system.md b/dev/docs/logical-theme-system.md
index 139055b3db26953670b03d4b31003232b6963286..84bd26a5387135921c16a40b9e3c8c1f44e13621 100644 (file)
--- a/dev/docs/logical-theme-system.md
+++ b/dev/docs/logical-theme-system.md
@@ -2,7 +2,9 @@
 
 BookStack allows logical customization via the theme system which enables you to add, or extend, functionality within the PHP side of the system without needing to alter the core application files.
 
 
 BookStack allows logical customization via the theme system which enables you to add, or extend, functionality within the PHP side of the system without needing to alter the core application files.
 

-WARNING: This system is currently in alpha so may incur changes. Once we've gathered some feedback on usage we'll look to removing this warning. This system will be considered semi-stable in the future. The `Theme::` system will be kept maintained but specific customizations or deeper app/framework usage using this system will not be supported nor considered in any way stable. Customizations using this system should be checked after updates.
+This is part of the theme system alongside the [visual theme system](./visual-theme-system.md).
+
+**Note:** This system is considered semi-stable. The `Theme::` system is kept maintained but specific customizations or deeper app/framework usage using this system will not be supported nor considered in any way stable. Customizations using this system should be checked after updates.

 
 ## Getting Started
 
 
 ## Getting Started
 

diff --git a/dev/docs/visual-theme-system.md b/dev/docs/visual-theme-system.md
index 6e7105a9ed06a8b8928bbb098760e87f445bb4cc..8a76ddb00e08432dd5e1b539009fcb5be138ded8 100644 (file)
--- a/dev/docs/visual-theme-system.md
+++ b/dev/docs/visual-theme-system.md
@@ -2,7 +2,9 @@
 
 BookStack allows visual customization via the theme system which enables you to extensively customize views, translation text & icons.
 
 
 BookStack allows visual customization via the theme system which enables you to extensively customize views, translation text & icons.
 

-This theme system itself is maintained and supported but usages of this system, including the files you are able to override, are not considered stable and may change upon any update. You should test any customizations made after updates.
+This is part of the theme system alongside the [logical theme system](./logical-theme-system.md).
+
+**Note:** This theme system itself is maintained and supported but usages of this system, including the files you are able to override, are not considered stable and may change upon any update. You should test any customizations made after updates.

 
 ## Getting Started
 
 
 ## Getting Started
 


@@ -32,3 +34,24 @@ return [
     'search' => 'find',
 ];
 ```
     'search' => 'find',
 ];
 ```

+
+## Publicly Accessible Files
+
+As part of deeper customizations you may want to expose additional files 
+(images, scripts, styles, etc...) as part of your theme, in a way so they're
+accessible in public web-space to browsers.
+
+To achieve this, you can put files within a `themes/<theme_name>/public` folder.
+BookStack will serve any files within this folder from a `/theme/<theme_name>` base path.
+
+As an example, if I had an image located at `themes/custom/public/cat.jpg`, I could access
+that image via the URL path `/theme/custom/cat.jpg`. That's assuming that `custom` is the currently
+configured application theme.
+
+There are some considerations to these publicly served files:
+
+- Only a predetermined range "web safe" content-types are currently served.
+  - This limits running into potential insecure scenarios in serving problematic file types.
+- A static 1-day cache time it set on files served from this folder.
+  - You can use alternative cache-breaking techniques (change of query string) upon changes if needed. 
+  - If required, you could likely override caching at the webserver level.