Update docs and re-enable dark mode with changes

docs/db/versions.md

@@ -9,17 +9,20 @@ The `Versions` table contains all the basic information about a version of GIFra
 | Table Name                          | Description                          |
 | ----------------------------------- | ------------------------------------ |
 | Versions                            | Contains the basic details about a version, including name, slug, start bound, theme and more |
-| VersionBasemaps                     | Contains an optional `BoundId` column used to define what bounds the layer covers |
-| VersionCategory                     | Contains a `BoundId` column used to define what bounds the basemap covers |
-| VersionPrintConfiguration           | Contains a `BoundId` column used to define what bounds the basemap covers |
-| VersionSearchDefinition             | Contains a `BoundId` column used to define what bounds the basemap covers |
-| VersionUser                         | Contains a `BoundId` column used to define what bounds the basemap covers |
+| VersionAnalytic                     | Identifies which analytics providers are enabled for a version |
+| VersionBasemaps                     | Contains details of the basemaps that a version has available and their default options |
+| VersionCategory                     | Contains a list of layer categories that a version has |
+| VersionContact                      | Lists the users that should be contacted regarding a version |
+| VersionLayer                        | Contains per-layer customisations applied to a version |
+| VersionPrintConfiguration           | Identifies which print configuration a version uses |
+| VersionSearchDefinition             | Lists the search definitions that are enabled in a version and their default settings |
+| VersionUser                         | Contains the users that have access to a version |
 
 ### Versions
 
 - `Name` - The name of the version. This also appears to the user in the top left
 - `Description` - A friendly description of the version. This also appears in the HTML meta description which is shown to search engines
-- `Slug` - The `Slug` is the bit on the end of the URL. You can have up to 3 parts to a slug, seperated by slashes. See section below on [slugs](#slugs) for more info
+- `Slug` - The `Slug` is the bit on the end of the URL. You can have up to 3 parts to a slug, seperated by slashes. See [slugs](../gui/versions.md#slugs) for more info
 - `Enabled` - A boolean indicating whether this version is enabled or not. Disabled versions will show a specific 'Disabled' message, rather than the standard 'Not found'
 - `RequireLogin` - A boolean indicating whether this version requires the user to login or not. Permissions need to be given to users using the [`VersionUser`](#versionuser) table.
 - `RedirectionURL` - An optional URL to redirect the user to instead of loading the version. Can be useful if a version changes slug, or you want to point people elsewhere. Will issue a `HTTP 302 Found` response with the URL provided
@@ -30,39 +33,13 @@ The `Versions` table contains all the basic information about a version of GIFra
 - `FeedbackURL` - An optional URL to a feedback form. A link will be put in the header of GIFramework Maps if this URL is filled in. If left blank, no feedback link will be generated.
 - `TourDetailsId` - The `Id` of a `TourDetails` to use in this version. Leave blank for no tour.
 - `ShowLogin` - A boolean indicating whether to show a login button on the version. If a user is already logged in, the account box will still always show, regardless of this setting
+- `VersionNotes` - An optional description of the version shown to administrators
 
-#### Slugs
+### VersionAnalytic
+The `VersionAnalytic` table defines which analytics providers are available in which versions.
 
-Slugs are the bit on the end of your application URL which direct you to different versions of GIFramework Maps. You can have a maximum of three slugs seperated by forward slashes. 
-
-By default, there should be one called 'general' which is where you will be directed if you have no slug on your URL.
-
-!!! danger "Reserved slugs"
-    There are a number of slugs that are reserved for use by the GIFramework Maps application. Using these will not work and may cause other unintended consequences. 
-
-    - `general`
-    - `account`
-    - `api`
-    - `print`
-    - `search`
-    - `broadcasthub`
-    - `css`
-    - `img`
-    - `lib`
-
-    You should not use these as the first part of the slug, regardless of any additional parts you put on the end, e.g. `lib/myversion` is **not** valid
-
-
-
-!!! example "Examples"
-    'general' -> Root of application e.g. `https://<your-application-root>/`
-
-    'highways' -> `https://<your-application-root>/highways`
-
-    'very/long/slug' -> `https://<your-application-root>/very/long/slug`
-
-
-
+- `VersionId` - The `Id` from the `Versions` table
+- `AnalyticsDefinitionId` - The `Id` from the `AnalyticsDefinition` table
 
 ### VersionBasemaps
 
@@ -88,6 +65,29 @@ The `VersionCategory` table defines which categories are available in which vers
 !!! info
     If your category is a child, both the parent AND child categories need to be added to this table.
 
+### VersionContact
+The `VersionContact` table defines which users should be contacted about a version.
+
+- `VersionContactId` - Unique ID for this entry
+- `VersionId` - The `Id` from the `Versions` table
+- `UserId` - The users unique identifier provided by the identity provider
+- `DisplayName` - The users display name
+- `Enabled` - Whether they should be included in the email drafting list
+
+### VersionLayer
+The `VersionLayer` table contains any per-layer customisations that have been applied to this version.
+
+- `VersionId` - The `Id` from the `Versions` table
+- `LayerId` - The `Id` from the `Layer` table
+- `CategoryId` - The `Id` from the `Category` table
+- `IsDefault` - Whether this layer is turned on by default or not
+- `DefaultOpacity` - The default opacity of the layer
+- `DefaultSaturation` - The default saturation of the layer
+- `SortOrder` - The position this layer appears within its category
+- `MaxZoom` - The maximum viewable zoom level of the layer
+- `MinZoom` - The minimum viewable zoom level of the layer
+- `Id` - Unique autogenerated ID for this customisation
+
 ### VersionPrintConfiguration
 
 The `VersionPrintConfiguration` table defines which print configurations are used in which versions.

docs/gui/versions.md

@@ -7,8 +7,9 @@ Versions are the best way to split maps up into different themes, with different
 Select **Create new version** and fill in the details:
 
 - Name
-- Slug - the bit at the end of the URL. For example: 'highways' -> `https://<your-application-root>/highways`
-- Description
+- Slug - the bit at the end of the URL. See [slugs](#slugs) for more information
+- Description (optional) - A friendly description that is shown to users and put in the metadata of the version
+- Version Notes (optional) - A description for administrators about this version
 - Theme - the [theme](../gui/themes.md) you want your version to use
 - Start extents - the [bound](../gui/bounds.md) to set the map to
 - Enabled - sets whether the version is enabled or not
@@ -19,7 +20,7 @@ Select **Create new version** and fill in the details:
 - Help URL (optional) - include a link to custom documentation
 - Feedback URL (optional) - include a link to a feedback form
 - Redirection URL (optional) - a URL to redirect the user to instead of loading the version. Can be useful if a version changes slug, or you want to point people elsewhere
-- Purge cache - ticking this box will purge the cache and allow your version to be available for testing or use straight away
+- Purge memory cache on save? - ticking this box will purge the cache and allow your version to be available for testing or use straight away
 
 On the right side of the screen, you'll see options for:
 
@@ -31,6 +32,86 @@ On the right side of the screen, you'll see options for:
 
 Select the version you want to edit. Make the changes you want and hit Save.
 
+On the right side of the screen you will also see new options for:
+
+- [Layer customisations](#layer-customisations) - allows you to customise how individual layers are configured for this specific version only
+- [Version contacts](#version-contacts) - add users who are considered a 'contact' for the version
+
 ## Delete a version
 
-Select the version you want to delete. You will be asked if you're sure, press Delete again to confirm.
+Select the version you want to delete. You will be asked if you're sure, press Delete again to confirm.
+
+## Slugs
+
+Slugs are the bit on the end of your application URL which direct you to different versions of GIFramework Maps. You can have a maximum of three slugs seperated by forward slashes. 
+
+By default, there should be one called 'general' which is where you will be directed if you have no slug on your URL.
+
+!!! danger "Reserved slugs"
+    There are a number of slugs that are reserved for use by the GIFramework Maps application. Using these will not work and may cause other unintended consequences. 
+
+    - `general`
+    - `account`
+    - `api`
+    - `print`
+    - `search`
+    - `broadcasthub`
+    - `css`
+    - `img`
+    - `lib`
+
+    You should not use these as the first part of the slug, regardless of any additional parts you put on the end, e.g. `lib/myversion` is **not** valid
+
+
+
+!!! example "Examples"
+    'general' -> Root of application e.g. `https://<your-application-root>/`
+
+    'highways' -> `https://<your-application-root>/highways`
+
+    'very/long/slug' -> `https://<your-application-root>/very/long/slug`
+
+# Layer customisations
+
+Layer customisations allow you to customise how individual layers are configured for this specific version only. The most common use is to turn one or many layers on by default, so users don't have to switch them on themselves, but you can also set the starting opacity/saturation, set the zoom levels and change where it appears within its category.
+
+You will be shown a list of all layers that are currently enabled in your version. Any that already have customisation will be at the top and highlighted.
+<figure markdown>
+![The layer customisations table for a version](../assets/images/customise-layers.png){width="650"}
+  <figcaption>The layer customisations table for a version</figcaption>
+</figure>
+
+Choose a layer you want to customise and you'll be taken to the customisations screen. You can set the following options on the layer:
+- On by default - Check to make this layer be switched on by default when the user opens this version
+- Minimum viewable zoom level - Set the minimum viewable zoom level. Zooming out beyond this level will switch the layer off automatically
+- Maximum viewable zoom level - Set the maximum viewable zoom level. Zooming in beyond this level will switch the layer off automatically
+- Sort order within category - Change the position it appears sorted in within its folder
+- Default opacity - Set the default opacity of the layer
+- Default saturation - Set the default saturation of the layer
+
+!!! note
+    Setting 'On by default' on a layer will override a users share link and always turn on the layer, so use with caution
+
+If you are editing an existing customisation, you can also delete the customisation using the Delete button.
+
+Every layer customisation applied to a version can be removed in one go by going to the Layer Customisations list and choosing 'Remove all custonisations'.
+
+# Version contacts
+
+Version contacts allow you to add one or many users as 'contacts' for the version. This could be for any reason, such as being the named person in charge of the version, or an interested party. Administrators can then use this list to quickly get in touch with relevant people for a version.
+
+Go the edit screen of a version, and choose the 'Version contacts' button on the right. You will be shown a list of any existing contacts and a button to add a contact entry.
+
+## Adding or editing a contact
+
+When you add a user, you can choose to provide a friendly name to identify them to administrators, in case the name provided by the identity provider is different.
+
+!!! note
+    The list of users comes from the list of users provided by your identity provider. There is no way at this time to add users who are not part of this list.
+
+You can check the 'Enable alerts for user' to make sure they are included in any emails or any future automated alert functionality.
+
+## Emailing users
+
+On the version contacts list, there is a button to 'Draft an email'. This will simply open an email addressed to all users with 'Yes' in the Mailing List column in your default mail program.
+

docs/index.md

@@ -2,5 +2,8 @@
 
 This guide will help you administer a standard installation of GIFramework Maps, either via the management interface (recommended) or via the database backend.
 
+!!! warning
+    We **highly** reccommend you use the management interface. Incorrect editing of the database directly can result in a broken application.
+
 * [Adminstration via the management interface](gui/getting-started.md)
 * [Administration via the backend database (advanced)](db/getting-started.md)

docs/stylesheets/custom.css

@@ -1,7 +1,9 @@
 :root {
-    --md-primary-fg-color:        #05476d;
-    --md-primary-fg-color--light: #00598c;
-    --md-primary-fg-color--dark:  #022e47;
+    --md-primary-fg-color: #05476d;
+    --md-accent-fg-color: #DE4259;
+  }
+  [data-md-color-scheme="slate"] {
+    --md-typeset-a-color: #DE4259;
   }
 body{
     font-family: system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",Arial,"Noto Sans","Liberation Sans",sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji";

mkdocs.yml

@@ -10,7 +10,30 @@ theme:
   features:
     - navigation.instant
   palette:
-    primary: custom
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      primary: custom
+      accent: custom
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      primary: custom
+      accent: custom
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: custom
+      accent: custom
+      toggle:
+        icon: material/weather-night
+        name: Switch to system preference
 markdown_extensions:
 - toc:
     permalink: true
@@ -21,16 +44,16 @@ markdown_extensions:
 - pymdownx.details
 - pymdownx.superfences
 - pymdownx.emoji:
-    emoji_index: !!python/name:materialx.emoji.twemoji
-    emoji_generator: !!python/name:materialx.emoji.to_svg
+    emoji_index: !!python/name:material.extensions.emoji.twemoji
+    emoji_generator: !!python/name:material.extensions.emoji.to_svg
 extra:
   social:
     - icon: fontawesome/brands/github 
       link: https://github.com/Dorset-Council-UK/GIFramework-Maps
 copyright: All content is available under the Open Government Licence v3.0 except where otherwise stated
 nav:
     - Home: 'index.md'
-    - 'Administration via the GUI':
+    - 'Administration via the management interface':
         - 'Getting started': 'gui/getting-started.md'
         - 'Atttributions': 'gui/attributions.md'
         - 'Bounds': 'gui/bounds.md'