diff --git a/index.adoc b/index.adoc index 500452774..63b62d154 100644 --- a/index.adoc +++ b/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[] diff --git a/reference.adoc b/reference.adoc index d624f6792..7e0efcc0e 100644 --- a/reference.adoc +++ b/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[] diff --git a/reference_themes_for_developers.adoc b/reference_themes_for_developers.adoc new file mode 100644 index 000000000..7618a0e56 --- /dev/null +++ b/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/`. + + diff --git a/reference_themes_for_users.adoc b/reference_themes_for_users.adoc new file mode 100644 index 000000000..90462db54 --- /dev/null +++ b/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! diff --git a/themes.adoc b/themes.adoc deleted file mode 100644 index 462509514..000000000 --- a/themes.adoc +++ /dev/null @@ -1,44 +0,0 @@ -[#themes] -=== Themes - -Temporary docs until I write something better. - -Very early version of a theme website: http://www.olivetin.app/themes/ - -If you're using a container, bind mount a "themes" directory from your host into /var/www/olivetin/themes/ - -If you're using a Linux package create a directory /var/www/olivetin/themes/ - -==== 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! diff --git a/upgrade_notes.adoc b/upgrade_notes.adoc new file mode 100644 index 000000000..d345398a3 --- /dev/null +++ b/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`. +