diff --git a/docs/20-quick-start.md b/docs/20-quick-start.md
index 7ad7306..3fbeeca 100644
--- a/docs/20-quick-start.md
+++ b/docs/20-quick-start.md
@@ -54,7 +54,7 @@ Try creating assets, agents, rules, users, realms, etc. using the Manager UI, so
 ## Where's the data stored?
 Persistent data is stored in a PostgreSQL DB which is stored in the `openremote_postgresql-data` Docker volume which is durably stored independently of the running containers (see all with `docker volume ls`).
 Note that historical attribute data is purged daily based on value of `OR_DATA_POINTS_MAX_AGE_DAYS`; this value can also be overridden for individual attributes by using the `dataPointsMaxAgeDays` configuration item.
-See the [Developer Guide](developer-guide/system-administration#backuprestore) for details on making backups of the database.
+See the [Developer Guide](developer-guide/100-system-administration.md#backuprestore) for details on making backups of the database.
 
 
 ## Contributing to OpenRemote
diff --git a/docs/developer-guide/160-frontend-testing.md b/docs/developer-guide/160-frontend-testing.md
index b99b1dd..a4998b5 100644
--- a/docs/developer-guide/160-frontend-testing.md
+++ b/docs/developer-guide/160-frontend-testing.md
@@ -71,7 +71,7 @@ The component tests are used to test individual Lit web components.
 
 ### Prerequisites
 
-Assuming you have set up your [development tooling](preparing-the-environment#development-tooling).
+Assuming you have set up your [development tooling](010-preparing-the-environment.md#development-tooling).
 
 1. Create a playwright configuration file `playwright.config.ts` in your component / app directory.
 
diff --git a/docs/tutorials/010-white-label-multi-tenant-iot-platform.md b/docs/tutorials/010-white-label-multi-tenant-iot-platform.md
index 7798e92..ead466c 100644
--- a/docs/tutorials/010-white-label-multi-tenant-iot-platform.md
+++ b/docs/tutorials/010-white-label-multi-tenant-iot-platform.md
@@ -8,7 +8,7 @@ White-labeling and multi-tenancy are part of the open-source core of OpenRemote
 
 ## Prerequisites
 
-- A running OpenRemote instance - see the [Quick Start](../quick-start).
+- A running OpenRemote instance - see the [Quick Start](../20-quick-start.md).
 - Superuser (`admin`) access to the **master** realm.
 - Your brand assets: a `logo.png`, a `logo-mobile.png`, a `favicon.png`, and your brand colour hex codes.
 
@@ -55,7 +55,7 @@ By default, superusers (e.g. `admin`) will see styling changes from `manager_con
 
 To verify per-tenant branding reliably, log in as a normal realm user.
 
-See [Custom deployment](../user-guide/deploying/custom-deployment) and the [Appearance page](../user-guide/manager-ui/appearance) for the full set of options.
+See [Custom deployment](../user-guide/010-deploying/10-custom-deployment.md) and the [Appearance page](../user-guide/020-manager-ui/30-appearance.md) for the full set of options.
 :::
 
 ## Step 3 - Serving each tenant
@@ -70,6 +70,6 @@ Your customer's realm is now available at its own URL (e.g. `iot.acme.com/manage
 
 ## Next steps
 
-- Lock down who can see what with [enterprise identity, SSO and RBAC](enterprise-identity-sso-rbac).
-- Let your customers' devices register themselves with [auto-provisioning at scale](auto-provision-devices-at-scale).
+- Lock down who can see what with [enterprise identity, SSO and RBAC](./060-enterprise-identity-sso-rbac.md).
+- Let your customers' devices register themselves with [auto-provisioning at scale](./080-auto-provision-devices-at-scale.md).
 - Build a customer-facing dashboard with the Insights dashboard builder.
diff --git a/docs/tutorials/020-open-weather-api-using-http-agent.md b/docs/tutorials/020-open-weather-api-using-http-agent.md
index 502e2cf..a2f9b7b 100644
--- a/docs/tutorials/020-open-weather-api-using-http-agent.md
+++ b/docs/tutorials/020-open-weather-api-using-http-agent.md
@@ -1,9 +1,9 @@
 # Using HTTP Agent for weather service
 
-This tutorial explains how to use the generic [HTTP Agent](../user-guide/agents-protocols/http) with an example to connect to the [OpenWeatherMap](https://openweathermap.org/) API.
+This tutorial explains how to use the generic [HTTP Agent](../user-guide/040-agents-protocols/050-http.md) with an example to connect to the [OpenWeatherMap](https://openweathermap.org/) API.
 
 :::note
-If you specifically want to connect to OpenWeatherMap, you can use the dedicated [OpenWeatherMap Agent](../user-guide/agents-protocols/openweathermap).
+If you specifically want to connect to OpenWeatherMap, you can use the dedicated [OpenWeatherMap Agent](../user-guide/040-agents-protocols/190-openweathermap.md).
 :::
 
 ## Prerequisites
diff --git a/docs/tutorials/040-receive-lorawan-sensor-data-from-chirpstack.md b/docs/tutorials/040-receive-lorawan-sensor-data-from-chirpstack.md
index 066e8db..290ef63 100644
--- a/docs/tutorials/040-receive-lorawan-sensor-data-from-chirpstack.md
+++ b/docs/tutorials/040-receive-lorawan-sensor-data-from-chirpstack.md
@@ -1,6 +1,6 @@
 # ChirpStack LoRaWAN Integration
 
-[ChirpStack](https://www.chirpstack.io/) is an open source LoRaWAN network server stack. This tutorial explains how to receive LoRaWAN sensor data via ChirpStack using the [MQTT Agent](../user-guide/agents-protocols/mqtt). The tutorial is based on the [Dragino LHT65](https://www.dragino.com/products/temperature-humidity-sensor/item/151-lht65.html) LoRaWAN sensor device as an example.
+[ChirpStack](https://www.chirpstack.io/) is an open source LoRaWAN network server stack. This tutorial explains how to receive LoRaWAN sensor data via ChirpStack using the [MQTT Agent](../user-guide/040-agents-protocols/090-mqtt.md). The tutorial is based on the [Dragino LHT65](https://www.dragino.com/products/temperature-humidity-sensor/item/151-lht65.html) LoRaWAN sensor device as an example.
 
 :::note
 This tutorial focuses on the **manual configuration** of MQTT agent links to provide a deeper understanding of the integration process.
diff --git a/docs/tutorials/050-connect-modbus-devices.md b/docs/tutorials/050-connect-modbus-devices.md
index fdb7b59..b22bfc3 100644
--- a/docs/tutorials/050-connect-modbus-devices.md
+++ b/docs/tutorials/050-connect-modbus-devices.md
@@ -8,7 +8,7 @@ The Modbus agent runs **inside the OpenRemote Manager** - there is no separate g
 
 ## Prerequisites
 
-- A running OpenRemote instance - see the [Quick Start](../quick-start).
+- A running OpenRemote instance - see the [Quick Start](../20-quick-start.md).
 - A reachable Modbus device: a Modbus TCP slave on your network, or a Modbus RTU device on a serial line accessible to the Manager host.
 - The device's register map (function code, address, data type, scaling).
 
@@ -18,7 +18,7 @@ The Modbus agent runs **inside the OpenRemote Manager** - there is no separate g
 2. For TCP, set the host/IP, port and the unit/slave ID.
 3. For RTU, set the serial port, baud rate, parity and stop bits, and the unit ID.
 
-See the [Modbus agent reference](../user-guide/agents-protocols/modbus) for all parameters.
+See the [Modbus agent reference](../user-guide/040-agents-protocols/080-modbus.md) for all parameters.
 
 ## Step 2 - Create the asset that represents the device
 
@@ -46,9 +46,9 @@ Writing to a holding register or coil lets you actuate the device (e.g. toggle a
 
 ## Step 5 - Turn raw values into insight
 
-Use [Flow rules](../user-guide/rules-and-forecasting/flow-rules) to derive virtual attributes (e.g. compute energy from power), and [When-Then rules](../user-guide/rules-and-forecasting/when-then-rules) to alarm on thresholds.
+Use [Flow rules](../user-guide/060-rules-and-forecasting/30-flow-rules.md) to derive virtual attributes (e.g. compute energy from power), and [When-Then rules](../user-guide/060-rules-and-forecasting/20-when-then-rules.md) to alarm on thresholds.
 
 ## Next steps
 
-- Deploy a local [edge gateway with a secure tunnel](edge-gateway-secure-tunnel) for sites with intermittent connectivity.
+- Deploy a local [edge gateway with a secure tunnel](./070-edge-gateway-secure-tunnel.md) for sites with intermittent connectivity.
 
diff --git a/docs/tutorials/060-enterprise-identity-sso-rbac.md b/docs/tutorials/060-enterprise-identity-sso-rbac.md
index 2f6f323..f3c974f 100644
--- a/docs/tutorials/060-enterprise-identity-sso-rbac.md
+++ b/docs/tutorials/060-enterprise-identity-sso-rbac.md
@@ -8,15 +8,15 @@ Industry-standard identity is built into the open-source core: Keycloak-based au
 
 ## Prerequisites
 
-- A running OpenRemote instance - see the [Quick Start](../quick-start).
-- Superuser access; ideally a [tenant realm already created](white-label-multi-tenant-iot-platform).
+- A running OpenRemote instance - see the [Quick Start](../20-quick-start.md).
+- Superuser access; ideally a [tenant realm already created](./010-white-label-multi-tenant-iot-platform.md).
 - For SSO/AD: access to your identity provider (Microsoft Entra ID/AD, Google, Okta, or any OIDC/SAML IdP).
 
 ## Step 1 - Understand the access model
 
 OpenRemote separates concerns into:
 
-- **Realms** - isolated tenants (see the [white-label tutorial](white-label-multi-tenant-iot-platform)).
+- **Realms** - isolated tenants (see the [white-label tutorial](./010-white-label-multi-tenant-iot-platform.md)).
 - **Roles** - what a user can do (read, write, configure, manage users, etc.).
 - **Restricted users** - users who can only see the specific assets linked to them (device- or customer-level access control).
 
@@ -34,7 +34,7 @@ Because identity is managed by Keycloak, you can federate to an external Identit
 2. Add an **Identity Provider** (OIDC or SAML) for your IdP and map claims/roles.
 3. Users now sign in with corporate credentials; access maps to OpenRemote roles automatically.
 
-To synchronise users/groups from a directory, follow [Linking to Active Directory](../user-guide/identity-and-security/linking-to-active-directory).
+To synchronise users/groups from a directory, follow [Linking to Active Directory](../user-guide/070-identity-and-security/30-linking-to-active-directory.md).
 
 ## Step 4 - Create OAuth2 service users for devices and integrations
 
@@ -52,9 +52,9 @@ Give each device or integration its own service user with a narrow role, so you
 
 1. Sign in via your IdP and confirm the SSO flow and resulting roles.
 2. Log in as a restricted user and confirm they see only their linked assets.
-3. Obtain a token for the service user and call a [REST API](../category/rest-api) endpoint.
+3. Obtain a token for the service user and call a [REST API](/docs/category/rest-api) endpoint.
 
 ## Next steps
 
-- Use these service users in the [MQTT/auto-provisioning](auto-provision-devices-at-scale) flow.
-- Apply per-tenant branding in the [white-label, multi-tenant tutorial](white-label-multi-tenant-iot-platform).
+- Use these service users in the [MQTT/auto-provisioning](./080-auto-provision-devices-at-scale.md) flow.
+- Apply per-tenant branding in the [white-label, multi-tenant tutorial](./010-white-label-multi-tenant-iot-platform.md).
diff --git a/docs/tutorials/070-edge-gateway-secure-tunnel.md b/docs/tutorials/070-edge-gateway-secure-tunnel.md
index 45d8759..dfaf4e2 100644
--- a/docs/tutorials/070-edge-gateway-secure-tunnel.md
+++ b/docs/tutorials/070-edge-gateway-secure-tunnel.md
@@ -8,13 +8,13 @@ The edge gateway is the **same OpenRemote codebase** running on-site, so an inst
 
 ## Prerequisites
 
-- Two OpenRemote instances: a **central** instance and an on-site **edge** instance (both from the [Quick Start](../quick-start) / Docker images; `amd64` and `arm64` are supported, so the edge can run on small hardware).
+- Two OpenRemote instances: a **central** instance and an on-site **edge** instance (both from the [Quick Start](../20-quick-start.md) / Docker images; `amd64` and `arm64` are supported, so the edge can run on small hardware).
 - Network access from the edge instance out to the central instance.
-- Read [OpenRemote as Edge Gateway](../user-guide/gateways-and-devices/edge-gateway).
+- Read [OpenRemote as Edge Gateway](../user-guide/080-gateways-and-devices/10-edge-gateway.md).
 
 ## Step 1 - Run OpenRemote on the edge
 
-Deploy a standard OpenRemote instance on the on-site hardware. Connect your local devices to it using whichever agents fit - [Modbus](connect-modbus-devices), [KNX](../user-guide/agents-protocols/knx), MQTT, Z-Wave, etc. The edge instance keeps working and storing data even if the uplink drops.
+Deploy a standard OpenRemote instance on the on-site hardware. Connect your local devices to it using whichever agents fit - [Modbus](./050-connect-modbus-devices.md), [KNX](../user-guide/040-agents-protocols/060-knx.md), MQTT, Z-Wave, etc. The edge instance keeps working and storing data even if the uplink drops.
 
 ## Step 2 - Register the gateway on the central instance
 
@@ -27,17 +27,17 @@ Configure the edge instance with the central instance's address and the gateway
 
 ## Step 4 - Remotely access the gateway UI via the secure tunnel
 
-Open the gateway's local UI from the central instance through the **secure tunnel**, so field engineers can configure and troubleshoot a site without a site visit or a public inbound port. Follow the tunnel setup in [OpenRemote as Edge Gateway](../user-guide/gateways-and-devices/edge-gateway).
+Open the gateway's local UI from the central instance through the **secure tunnel**, so field engineers can configure and troubleshoot a site without a site visit or a public inbound port. Follow the tunnel setup in [OpenRemote as Edge Gateway](../user-guide/080-gateways-and-devices/10-edge-gateway.md).
 
 :::caution
-Restrict who can open tunnels and access gateway UIs using [roles and restricted users](enterprise-identity-sso-rbac); remote access to field equipment should be tightly scoped.
+Restrict who can open tunnels and access gateway UIs using [roles and restricted users](./060-enterprise-identity-sso-rbac.md); remote access to field equipment should be tightly scoped.
 :::
 
 ## Step 5 - Decide what runs where
 
-Keep latency-sensitive control and local automation in [edge rules](../user-guide/rules-and-forecasting/create-rules), and use the central instance for cross-site dashboards, fleet-wide rules and long-term analytics.
+Keep latency-sensitive control and local automation in [edge rules](../user-guide/060-rules-and-forecasting/10-create-rules.md), and use the central instance for cross-site dashboards, fleet-wide rules and long-term analytics.
 
 ## Next steps
 
-- Push [OTA firmware updates](ota-firmware-updates-with-hawkbit) to devices behind the gateway.
-- Onboard edge devices automatically with [auto-provisioning](auto-provision-devices-at-scale).
+- Push [OTA firmware updates](./090-ota-firmware-updates-with-hawkbit.md) to devices behind the gateway.
+- Onboard edge devices automatically with [auto-provisioning](./080-auto-provision-devices-at-scale.md).
diff --git a/docs/tutorials/080-auto-provision-devices-at-scale.md b/docs/tutorials/080-auto-provision-devices-at-scale.md
index 053e7b6..a22d318 100644
--- a/docs/tutorials/080-auto-provision-devices-at-scale.md
+++ b/docs/tutorials/080-auto-provision-devices-at-scale.md
@@ -8,7 +8,7 @@ Provisioning in OpenRemote creates the client credentials **and** the digital as
 
 ## Prerequisites
 
-- A running OpenRemote instance - see the [Quick Start](../quick-start).
+- A running OpenRemote instance - see the [Quick Start](../20-quick-start.md).
 - Superuser access to a realm where your devices will live.
 - A device (or test client) that can do MQTT over TLS with an X.509 client certificate - for example an ESP32/ESP8266.
 
@@ -23,7 +23,7 @@ Decide what each device *is* in your model (e.g. a `Thing`, or a custom `Environ
 3. Select the **asset type** to create per device and set the realm.
 4. Choose whether to **auto-link attributes** to standard MQTT topics and whether newly provisioned assets are **disabled until approved** (useful for a manufacturing QA gate).
 
-See [Auto provisioning devices and users](../user-guide/gateways-and-devices/auto-provisioning) for the message format and the full configuration reference.
+See [Auto provisioning devices and users](../user-guide/080-gateways-and-devices/20-auto-provisioning.md) for the message format and the full configuration reference.
 
 ## Step 3 - Flash devices with a unique certificate
 
@@ -37,7 +37,7 @@ On first connection the device publishes a provisioning request to the provision
 2. Links its attributes to the device's publish/subscribe topics.
 3. Returns the asset ID so the device can start publishing telemetry immediately.
 
-For a concrete firmware example, follow [Connect ESP32 or ESP8266 using MQTT](../user-guide/gateways-and-devices/connect-esp32-or-esp8266-using-mqtt), then point it at your provisioning config instead of a manually created service user.
+For a concrete firmware example, follow [Connect ESP32 or ESP8266 using MQTT](../user-guide/080-gateways-and-devices/30-connect-esp32-or-esp8266-using-mqtt.md), then point it at your provisioning config instead of a manually created service user.
 
 ## Step 5 - Verify and scale
 
@@ -46,10 +46,10 @@ For a concrete firmware example, follow [Connect ESP32 or ESP8266 using MQTT](..
 3. Roll out the remaining fleet - no manual asset creation required.
 
 :::note
-Combine this with [multi-tenant realms](./white-label-multi-tenant-iot-platform) so each customer's devices provision straight into that customer's realm.
+Combine this with [multi-tenant realms](./010-white-label-multi-tenant-iot-platform.md) so each customer's devices provision straight into that customer's realm.
 :::
 
 ## Next steps
 
-- Keep field devices current with [OTA firmware updates using hawkBit](ota-firmware-updates-with-hawkbit).
-- Deploy a local [edge gateway with a secure tunnel](edge-gateway-secure-tunnel) for sites with intermittent connectivity.
+- Keep field devices current with [OTA firmware updates using hawkBit](./090-ota-firmware-updates-with-hawkbit.md).
+- Deploy a local [edge gateway with a secure tunnel](./070-edge-gateway-secure-tunnel.md) for sites with intermittent connectivity.
diff --git a/docs/tutorials/090-ota-firmware-updates-with-hawkbit.md b/docs/tutorials/090-ota-firmware-updates-with-hawkbit.md
index 52cbdb7..4154efb 100644
--- a/docs/tutorials/090-ota-firmware-updates-with-hawkbit.md
+++ b/docs/tutorials/090-ota-firmware-updates-with-hawkbit.md
@@ -8,17 +8,17 @@ OpenRemote integrates a purpose-built rollout engine (hawkBit) for **device life
 
 ## Prerequisites
 
-- A running OpenRemote instance - see the [Quick Start](../quick-start).
+- A running OpenRemote instance - see the [Quick Start](../20-quick-start.md).
 - A hawkBit instance reachable from OpenRemote (can be co-located with your stack).
 - Devices whose firmware can poll a hawkBit DDI endpoint and apply an update image.
 
 ## Step 1 - Enable the hawkBit integration
 
-Configure OpenRemote to connect to your hawkBit server. Once linked, OpenRemote can represent firmware/device-update state on your assets and surface update actions. See [Firmware updating with Hawkbit](../user-guide/gateways-and-devices/firmware-updating-with-hawkbit) for the supported features and configuration.
+Configure OpenRemote to connect to your hawkBit server. Once linked, OpenRemote can represent firmware/device-update state on your assets and surface update actions. See [Firmware updating with Hawkbit](../user-guide/080-gateways-and-devices/40-firmware-updating-with-hawkbit.md) for the supported features and configuration.
 
 ## Step 2 - Register devices as hawkBit targets
 
-Each device becomes a **target** in hawkBit. Use a consistent target/controller ID (for example the same serial used during [auto-provisioning](auto-provision-devices-at-scale)) so a device's OpenRemote asset and its hawkBit target line up one-to-one.
+Each device becomes a **target** in hawkBit. Use a consistent target/controller ID (for example the same serial used during [auto-provisioning](./080-auto-provision-devices-at-scale.md)) so a device's OpenRemote asset and its hawkBit target line up one-to-one.
 
 ## Step 3 - Upload a software module and distribution set
 
@@ -38,9 +38,9 @@ Always start with a small canary group and verify devices come back online and r
 
 ## Step 5 - Track update status in OpenRemote
 
-Monitor update progress and firmware version on the device assets in the Manager. Combine this with [rules](../user-guide/rules-and-forecasting/create-rules) to alert an operator if a device fails to check in after an update.
+Monitor update progress and firmware version on the device assets in the Manager. Combine this with [rules](../user-guide/060-rules-and-forecasting/10-create-rules.md) to alert an operator if a device fails to check in after an update.
 
 ## Next steps
 
-- Trigger update alerts and escalation with [ML Forecasting Service](../user-guide/services/service-ml-forecast).
-- Manage on-site devices behind an [edge gateway with a secure tunnel](../user-guide/gateways-and-devices/edge-gateway).
+- Trigger update alerts and escalation with [ML Forecasting Service](../user-guide/100-services/20-service-ml-forecast.md).
+- Manage on-site devices behind an [edge gateway with a secure tunnel](../user-guide/080-gateways-and-devices/10-edge-gateway.md).
diff --git a/docs/tutorials/110-change-celsius-to-fahrenheit-with-flow.md b/docs/tutorials/110-change-celsius-to-fahrenheit-with-flow.md
index cbb1d5e..bea1a02 100644
--- a/docs/tutorials/110-change-celsius-to-fahrenheit-with-flow.md
+++ b/docs/tutorials/110-change-celsius-to-fahrenheit-with-flow.md
@@ -4,7 +4,7 @@ This tutorial offers an example for converting an attribute value, using the Flo
 
 ## Prerequisites
 
-- A running OpenRemote instance - see the [Quick Start](../quick-start).
+- A running OpenRemote instance - see the [Quick Start](../20-quick-start.md).
 
 ## Step 1 - Create a new attribute
 
diff --git a/docs/user-guide/020-manager-ui/10-manager-ui.md b/docs/user-guide/020-manager-ui/10-manager-ui.md
index e6c90a0..e95f7f6 100644
--- a/docs/user-guide/020-manager-ui/10-manager-ui.md
+++ b/docs/user-guide/020-manager-ui/10-manager-ui.md
@@ -82,7 +82,7 @@ See the documentation page [explaining all available configuration item options
 
 ### Create an agent
 
-Agents are a specific type of asset used to connect to external sensors, actuators, gateways, or services using protocols. They are added in the same manner as assets by clicking the `+` in the header of the asset tree. This will open a modal that shows the available agent types at the top of the list. You will see the generic ones: [HTTP](../040-agents-protocols/050-http.md), [WebSocket](../040-agents-protocols/170-websocket-agent.md), [MQTT](../040-agents-protocols/090-mqtt.md), [TCP](../040-agents-protocols/130-tcp.md), [UDP](../040-agents-protocols/150-udp.md) and [SNMP](../040-agents-protocols/110-snmp.md); as well as more specific ones like [Z-Wave](../agents-protocols/z-wave), [KNX](../agents-protocols/knx) or [Velbus](../040-agents-protocols/160-velbus.md).
+Agents are a specific type of asset used to connect to external sensors, actuators, gateways, or services using protocols. They are added in the same manner as assets by clicking the `+` in the header of the asset tree. This will open a modal that shows the available agent types at the top of the list. You will see the generic ones: [HTTP](../040-agents-protocols/050-http.md), [WebSocket](../040-agents-protocols/170-websocket-agent.md), [MQTT](../040-agents-protocols/090-mqtt.md), [TCP](../040-agents-protocols/130-tcp.md), [UDP](../040-agents-protocols/150-udp.md) and [SNMP](../040-agents-protocols/110-snmp.md); as well as more specific ones like [Z-Wave](../040-agents-protocols/180-z-wave.md), [KNX](../040-agents-protocols/060-knx.md) or [Velbus](../040-agents-protocols/160-velbus.md).
 Once you create an Agent, the agent page will display the relevant attributes, required to establish an actual connection to the external world.
 
 Some Agents have auto discovery (e.g. Z-Wave) or use configuration files (e.g. KNX and Velbus). The Agent page will show a discovery button or a file selector. Once set correctly, the Agent will also create an additional asset/attribute structure for all discovered or configured assets.
diff --git a/docs/user-guide/020-manager-ui/30-appearance.md b/docs/user-guide/020-manager-ui/30-appearance.md
index 7ef3901..8257d94 100644
--- a/docs/user-guide/020-manager-ui/30-appearance.md
+++ b/docs/user-guide/020-manager-ui/30-appearance.md
@@ -699,7 +699,7 @@ If you want to adjust the map styling. You can change the map under Map Settings
 | Method                   | Description                                                                                                                                                                                                                                                                           | When to use?                                                                                |
 | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
 | Tile server           | Configure a tile server (note that this get's priority over the custom map tiles). | If you want to use an external map tile server.                                           |
-| Custom Map Tiles           | The uploaded map will be used instead of the default (see [working on maps](../../developer-guide/working-on-maps#uploading-mbtiles) for more).                                                                                                                                       | If you happen to have an `.mbtiles` file and  want to view a different part of the world.   |
+| Custom Map Tiles           | The uploaded map will be used instead of the default (see [working on maps](../../developer-guide/130-working-on-maps.md#uploading-mbtiles) for more).                                                                                                                                       | If you happen to have an `.mbtiles` file and  want to view a different part of the world.   |
 | Style JSON URL           | Override the default map settings with a `style.json` URL (e.g. `https://api.example.com/maps/streets/style.json?key=your_key`) from a Map/Tile provider that supports MapLibre (see [providers](https://github.com/maplibre/awesome-maplibre?tab=readme-ov-file#maptile-providers)). | If you want to configure a different map quickly.                                           |
 | Map Layers    | After configuring a Style JSON URL you can import it to include the layers allowing you to adjust the map styling. You may optionally configure a Tile server URL (to see more of a map).                                                                                             | If you want to be able to edit the map styling in OpenRemote, but also use an external map. |
 | Realm Map Setting        | You can set boundaries, zoom levels and center points, as well as add GeoJSON based points, lines and shapes from GeoJSON files. For creating GeoJSON files, you can use e.g. https://geojson.io/. For searching existing GeoJSON map layers, you can use https://overpass-turbo.eu/.                                                           | If you want to change focus of the map or add map layers per realm.                                                    |
diff --git a/docs/user-guide/040-agents-protocols/210-disabled-protocols/10-artnet-dmx-agent.md b/docs/user-guide/040-agents-protocols/210-disabled-protocols/10-artnet-dmx-agent.md
index b607473..36166cf 100644
--- a/docs/user-guide/040-agents-protocols/210-disabled-protocols/10-artnet-dmx-agent.md
+++ b/docs/user-guide/040-agents-protocols/210-disabled-protocols/10-artnet-dmx-agent.md
@@ -6,7 +6,7 @@
 
 :::
 
-The example below describes interactively linking asset attributes to Artnet Servers using the [ArtnetClientProtocol](https://github.com/openremote/openremote/blob/master/agent/src/main/java/org/openremote/agent/protocol/dmx/artnet/ArtnetClientProtocol.java). The following examples assume that you are running the [Demo Docker Compose profile](../../../developer-guide/docker-compose-profiles#demo-docker-composeyml).
+The example below describes interactively linking asset attributes to Artnet Servers using the [ArtnetClientProtocol](https://github.com/openremote/openremote/blob/master/agent/src/main/java/org/openremote/agent/protocol/dmx/artnet/ArtnetClientProtocol.java). The following examples assume that you are running the [Demo Docker Compose profile](../../../developer-guide/030-docker-compose-profiles.md#demo-docker-composeyml).
 
 ## Setup the basic Artnet connection
 The following examples assume that the DMX controller is bound to the loopback address `127.0.0.1` on port `6454`:
diff --git a/docs/user-guide/070-identity-and-security/10-realms-users-and-roles.md b/docs/user-guide/070-identity-and-security/10-realms-users-and-roles.md
index 1982679..03c222e 100644
--- a/docs/user-guide/070-identity-and-security/10-realms-users-and-roles.md
+++ b/docs/user-guide/070-identity-and-security/10-realms-users-and-roles.md
@@ -3,7 +3,7 @@
 Authentication and Authorization in the OpenRemote stack is powered by the [Keycloak](https://www.keycloak.org/) `OpenID Connect Provider` and utilises `OAuth 2.0`. Generally within an instance of the OpenRemote stack the Keycloak server is accessible at: `/auth` but should only be used by advanced users that know what they're doing as **you can completely break your instance**.
 
 ## Realms
-Realms (also known as Tenants) in OpenRemote provide a layer of isolation with each realm having their own users, assets, rules and even UI styling. This allows for multi-tenancy use cases and realms can only be managed by superusers. A realm user can only see and access their own realm and resources within this realm, super users are able to access all realms. Individual Realms can be reached at `https://youradress/manager/?realm=realmname`. For more details, see [Realms](../manager-ui/#realms).
+Realms (also known as Tenants) in OpenRemote provide a layer of isolation with each realm having their own users, assets, rules and even UI styling. This allows for multi-tenancy use cases and realms can only be managed by superusers. A realm user can only see and access their own realm and resources within this realm, super users are able to access all realms. Individual Realms can be reached at `https://youradress/manager/?realm=realmname`. For more details, see [Realms](../020-manager-ui/10-manager-ui.md#realms).
 
 ## Users
 There are two basic types of user within OpenRemote, all can be managed within the Manager UI or programmatically via custom setup code:
diff --git a/docusaurus.config.ts b/docusaurus.config.ts
index 4b6eae4..ba7ffc6 100644
--- a/docusaurus.config.ts
+++ b/docusaurus.config.ts
@@ -109,7 +109,7 @@ const config: Config = {
   markdown: {
     mermaid: true,
     hooks: {
-        onBrokenMarkdownLinks: 'warn',
+        onBrokenMarkdownLinks: 'throw',
     },
   },