Added upgrade notes

index.adoc

@@ -107,12 +107,12 @@ include::dashboards.adoc[]
 
 include::entities.adoc[]
 
-include::advanced_configuration.adoc[]
-
 include::authorization.adoc[]
 
 include::solutions.adoc[]
 
+include::advanced_configuration.adoc[]
+
 include::reference.adoc[]
 
 include::troubleshooting.adoc[]

reference.adoc

@@ -14,4 +14,8 @@ include::reference_multipleInstances.adoc[]
 
 include::reference_snapshots.adoc[]
 
-include::themes.adoc[]
+include::reference_themes_for_users.adoc[]
+
+include::reference_themes_for_developers.adoc[]
+
+include::upgrade_notes.adoc[]

reference_themes_for_developers.adoc

@@ -0,0 +1,8 @@
+[#themes-dev]
+=== Themes (for developers)
+
+include::snippit_earlydoc.adoc[]
+
+OliveTin will load `/theme.css` depending on `themeName:` in your config file. Images and any other assets will be served at `/custom-webui/themes/mytheme/`.
+
+

reference_themes_for_users.adoc

@@ -0,0 +1,65 @@
+[#themes]
+=== Themes (for users)
+
+include::snippit_earlydoc.adoc[]
+
+Very early version of a theme website: http://www.olivetin.app/themes/
+
+==== The custom-webui directory
+
+OliveTin will server a directory called `custom-webui` at `http://yourserver:1337/custom-webui/`, this means that all theme content should go into `custom-webui/themes`.
+
+In the past, OliveTin used to lookup the theme name and send that theme name to your browser so that it could then manually request the theme stylesheet. This approach was slow, it stopped browsers caching, and it caused an awkward "flash" whenever the new theme was loaded. Now, OliveTin internally looks up your theme.css file based on your `themeName`, and will always serve this `theme.css` file at `http://yourServer:1337/theme.css`. If you are not using a custom theme, OliveTin will just serve an empty CSS file.
+
+Install Themes into your **custom-webui** directory, which should be in your config directory. If this directory does not exist, you can create it.
+
+[source,yaml]
+----
+├── config.yaml
+├── custom-webui
+│   └── themes
+│       └── custom-icons
+│           ├── icon.png
+│           └── theme.css
+├── entities
+│   ├── containers.json
+│   ├── heating.yaml
+│   ├── servers2.yml
+│   ├── servers.yaml
+│   └── systemd_units.json
+└── installation-id.txt
+----
+
+==== Create your own theme (without any intention of publishing it)
+
+Create a sub-directory under your theme directory (normally /var/www/olivetin/themes) called "mytheme"
+
+Set your theme in your config
+
+[source,yaml]
+.`config.yaml`
+----
+themeName: mytheme
+----
+
+Add your css into /var/www/olivetin/themes/mytheme/theme.css
+
+Your theme css will be loaded "on top" of the existing stylesheet.
+
+To test it is working, set your theme CSS to something ridiculous like;
+
+----
+body {
+    background-color: red !important;
+}
+----
+
+Profit.
+
+==== Create a theme for other people to use
+
+. Use this GitHub repository as a template to create your own theme repo: https://github.com/OliveTin/theme-template
+. Fork https://github.com/olivetin/themes
+. Create a directory under "content/posts" called something like "mytheme", and populate index.md, and cover.png. 
+. Raise a pull request back to github.com/olivetin/themes/
+. Rejoice!

upgrade_notes.adoc

@@ -0,0 +1,59 @@
+[#upgrade-notes]
+=== Upgrade Notes
+
+OliveTin releases are published to GitHub, and the release notes are contained there. This page includes a summary of "Upgrade Notes" for breaking changes between releases.
+
+==== 2024.04.09
+
+===== Themes Directory (for theme users)
+
+====== Background
+
+Until now, OliveTin has served the themes directory from the "webui" directory, normally `/var/www/olivetin/themes` on most installations. If you wanted to install a theme, you would put the theme in to that directory.
+
+This was a bit cumbersome, because OliveTin treats the content of the "webui" directory as disposable / part of the system, whereas themes are much more like "user data" and "configuration". It also meant that people using Linux Containers had to bind-mount a separate directory for themes.
+
+====== Upgrade
+
+Now themes are stored in the "configdir" (wherever OliveTin finds it's config file, eg `/config` in containers), under the subdirectory `custom-webui/themes`. OliveTin will try to create the `custom-webui` folder in your configdir if it doesn't find it.
+
+The advantage of this change is that themes are stored with your config, as part of your data. 
+
+To upgrade, simply move any themes you might have into your configdir, under `custom-webui/themes/`. eg:
+
+[source,yaml]
+----
+.
+├── config.yaml
+├── custom-webui
+│   └── themes
+│       └── custom-icons
+│           ├── icon.png
+│           └── theme.css
+├── entities
+│   ├── containers.json
+│   ├── heating.yaml
+│   ├── servers2.yml
+│   ├── servers.yaml
+│   └── systemd_units.json
+└── installation-id.txt
+----
+
+===== Theme Asset Paths (for theme developers)
+
+====== Background
+
+OliveTin had to send the theme name to the browser, so that some javascript could then request `http://yourServer:1337/themes/myTheme/theme.css`, and load it as a stylesheet. This had the following problems;
+
+. This was slow (could take up to a second)
+. This creates a "flash" in the browser, as the new theme.css is loaded over the top of the existing stylesheet.
+. Browsers could not cache this theme.css with the page load.
+
+====== Upgrade
+
+The new behavior is that OliveTin will always try to load `http://yourServer:1337/theme.css` as part of the static HTML that is sent to the browser. This means that regular caching can cache the theme.css, and this effectively elliminates the slowness and "flashing" when the browser renders the page.
+
+Internally, OliveTin maps `http://yourServer:1337/theme.css` to the `theme.css` of whatever the theme is set to with `themeName`, for example, it could map to `themes/myTheme/theme.css`.
+
+As a theme developer, normally you would reference a background image, or similar using `./background.png`, but OliveTin is loading the theme.css as the directory root, and the themes' assets from the custom-webui theme directory. Therefore you need to update paths to be like; `background-image: "/custom-webui/themes/myTheme/background.png`.
+