Use filename prefixes for doc ordering (#164)#172
Merged
Conversation
7a1111e to
4097899
Compare
Rename hand-authored /docs/ files and user-guide sub-folders with NN- prefixes (increments of 10) reflecting the current sidebar order. Remove sidebar_position frontmatter and _category_.json position, and rewrite relative markdown links to the prefixed targets. Docusaurus strips the number prefix from doc id/label/URL, so public URLs are unchanged.
manager-ui.md and services.md match their folder name, so Docusaurus served them at the folder path. Number prefixes break that match, so pin the original URLs with a slug to avoid a URL change.
4097899 to
38f478d
Compare
The link used a site-absolute path with NN- filename prefixes and a .md extension; convert to a relative path so all internal doc links follow the same convention.
There was a problem hiding this comment.
Pull request overview
This PR migrates Docusaurus doc ordering from sidebar_position/position metadata to numeric filename/folder prefixes (in steps of 10), making ordering visible in the tree while aiming to keep public URLs stable by relying on Docusaurus’ prefix-stripping behavior (and pinned slugs where needed).
Changes:
- Renamed/reorganized docs under numeric
NN-prefixes and removedsidebar_positionfrontmatter plus_category_.jsonposition. - Rewrote relative Markdown links to point at the new prefixed targets; added/adjusted
slugfrontmatter for key index pages. - Added/updated several documentation pages and supporting images during the migration.
Reviewed changes
Copilot reviewed 101 out of 168 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| docs/user-guide/deploying/configuring-the-manager-ui.md | Removed/relocated doc as part of moving Deploying docs to prefixed folder structure. |
| docs/user-guide/110-anomaly-detection.md | Updated forecasting link to new prefixed path. |
| docs/user-guide/100-services/img/service-ml-forecast-tree.png | Added/updated image asset for Services docs. |
| docs/user-guide/100-services/20-service-ml-forecast.md | Removed sidebar_position; updated External Services link to prefixed path. |
| docs/user-guide/100-services/10-services.md | Added explicit slug for Services index page. |
| docs/user-guide/100-services/category.json | Removed category position to rely on filename ordering. |
| docs/user-guide/090-domains/20-fleet-management.md | Removed sidebar_position for filename-based ordering. |
| docs/user-guide/090-domains/10-create-your-energy-management-system.md | Updated multiple relative links to new prefixed targets. |
| docs/user-guide/090-domains/category.json | Removed category position. |
| docs/user-guide/080-gateways-and-devices/img/manager-interconnect.png | Added/updated image asset for Gateways & Devices docs. |
| docs/user-guide/080-gateways-and-devices/img/manager-asset-synchronisation.png | Added/updated image asset for Gateways & Devices docs. |
| docs/user-guide/080-gateways-and-devices/50-mqtt-gateway-api.md | Added new (unlisted) MQTT Gateway API documentation. |
| docs/user-guide/080-gateways-and-devices/40-firmware-updating-with-hawkbit.md | Removed sidebar_position. |
| docs/user-guide/080-gateways-and-devices/30-connect-esp32-or-esp8266-using-mqtt.md | Removed sidebar_position; updated links to prefixed tutorial/user-guide targets. |
| docs/user-guide/080-gateways-and-devices/20-auto-provisioning.md | Removed sidebar_position; updated Manager APIs link to prefixed doc. |
| docs/user-guide/080-gateways-and-devices/10-edge-gateway.md | Removed sidebar_position; updated gateway tunnelling link to prefixed doc. |
| docs/user-guide/080-gateways-and-devices/category.json | Removed category position. |
| docs/user-guide/070-identity-and-security/30-linking-to-active-directory.md | Removed sidebar_position. |
| docs/user-guide/070-identity-and-security/20-asset-security.md | Removed sidebar_position. |
| docs/user-guide/070-identity-and-security/10-realms-users-and-roles.md | Removed sidebar_position; updated Manager APIs link to prefixed doc. |
| docs/user-guide/070-identity-and-security/category.json | Removed category position. |
| docs/user-guide/060-rules-and-forecasting/60-geojson-geofencing.md | Added new GeoJSON geofencing documentation page. |
| docs/user-guide/060-rules-and-forecasting/50-forecasting.md | Removed sidebar_position; updated Domains links to prefixed paths. |
| docs/user-guide/060-rules-and-forecasting/40-groovy-rules.md | Removed sidebar_position; updated links to prefixed rules/manager-ui docs. |
| docs/user-guide/060-rules-and-forecasting/30-flow-rules.md | Removed sidebar_position; updated “See Also” links to prefixed targets. |
| docs/user-guide/060-rules-and-forecasting/20-when-then-rules.md | Removed sidebar_position; updated Manager UI links to prefixed targets. |
| docs/user-guide/060-rules-and-forecasting/10-create-rules.md | Removed sidebar_position; updated intra-folder links to prefixed targets. |
| docs/user-guide/060-rules-and-forecasting/category.json | Removed category position. |
| docs/user-guide/050-manager-apis.md | Removed sidebar_position; updated Asset Security link to prefixed path. |
| docs/user-guide/040-agents-protocols/img/teltonika-telematics.png | Added/updated partner image asset. |
| docs/user-guide/040-agents-protocols/img/teltonika-networks.png | Added/updated partner image asset. |
| docs/user-guide/040-agents-protocols/img/seeed-studio.jpg | Added/updated partner image asset. |
| docs/user-guide/040-agents-protocols/220-velbus-serial.md | Updated Developer Guide link to prefixed “Working on UI and apps”. |
| docs/user-guide/040-agents-protocols/210-disabled-protocols/30-or-controller-2.5-agent.md | Removed sidebar_position; updated multiple links to prefixed targets. |
| docs/user-guide/040-agents-protocols/210-disabled-protocols/20-ikea-trådfri-agent.md | Removed sidebar_position; updated multiple links to prefixed targets. |
| docs/user-guide/040-agents-protocols/210-disabled-protocols/10-artnet-dmx-agent.md | Removed sidebar_position; updated multiple links to prefixed targets. |
| docs/user-guide/040-agents-protocols/210-disabled-protocols/category.json | Removed category position. |
| docs/user-guide/040-agents-protocols/200-partner-integrations.md | Removed sidebar_position; updated Manager APIs link to prefixed doc. |
| docs/user-guide/040-agents-protocols/190-openweathermap.md | Removed sidebar_position; updated Agent Link Overview reference to prefixed file. |
| docs/user-guide/040-agents-protocols/180-z-wave.md | Removed sidebar_position; updated overview references to prefixed file. |
| docs/user-guide/040-agents-protocols/170-websocket-agent.md | Removed sidebar_position; updated overview references to prefixed file. |
| docs/user-guide/040-agents-protocols/160-velbus.md | Removed sidebar_position; updated overview references to prefixed file. |
| docs/user-guide/040-agents-protocols/150-udp.md | Removed sidebar_position; updated overview reference to prefixed file. |
| docs/user-guide/040-agents-protocols/140-the-things-stack.md | Removed sidebar_position; updated overview reference to prefixed file. |
| docs/user-guide/040-agents-protocols/130-tcp.md | Removed sidebar_position; updated overview references to prefixed file. |
| docs/user-guide/040-agents-protocols/120-serial.md | Removed sidebar_position; updated overview references to prefixed file. |
| docs/user-guide/040-agents-protocols/110-snmp.md | Removed sidebar_position; updated overview reference to prefixed file. |
| docs/user-guide/040-agents-protocols/100-simulator.md | Removed sidebar_position; updated overview reference to prefixed file. |
| docs/user-guide/040-agents-protocols/090-mqtt.md | Removed sidebar_position; updated Manager APIs & overview links to prefixed docs. |
| docs/user-guide/040-agents-protocols/080-modbus.md | Removed sidebar_position. |
| docs/user-guide/040-agents-protocols/070-lora.md | Removed sidebar_position; updated ChirpStack/TTS/tutorial links to prefixed docs. |
| docs/user-guide/040-agents-protocols/060-knx.md | Removed sidebar_position; updated overview references to prefixed file. |
| docs/user-guide/040-agents-protocols/050-http.md | Removed sidebar_position; updated overview references to prefixed file. |
| docs/user-guide/040-agents-protocols/040-email.md | Removed sidebar_position. |
| docs/user-guide/040-agents-protocols/030-chirpstack.md | Removed sidebar_position; updated overview reference to prefixed file. |
| docs/user-guide/040-agents-protocols/020-bluetooth-mesh.md | Removed sidebar_position; updated overview references to prefixed file. |
| docs/user-guide/040-agents-protocols/010-overview.md | Removed sidebar_position. |
| docs/user-guide/040-agents-protocols/_lorawan-asset-types.md | Updated ChirpStack/TTS links to prefixed docs. |
| docs/user-guide/040-agents-protocols/category.json | Removed category position. |
| docs/user-guide/030-assets-agents-and-attributes.md | Removed sidebar_position; updated links to Manager UI and Agents overview. |
| docs/user-guide/020-manager-ui/40-geocoding.md | Removed sidebar_position; updated internal links and Developer Guide link. |
| docs/user-guide/020-manager-ui/30-appearance.md | Removed sidebar_position; updated Custom Deployment link to prefixed path. |
| docs/user-guide/020-manager-ui/20-on-mobile.md | Removed sidebar_position; updated Deploying/Dev Guide/Architecture/Tutorial links. |
| docs/user-guide/020-manager-ui/10-manager-ui.md | Added explicit slug; updated many links to prefixed targets across the guide. |
| docs/user-guide/020-manager-ui/category.json | Removed category position. |
| docs/user-guide/010-deploying/80-release-management.md | Removed sidebar_position; updated links to prefixed deployment/dev docs. |
| docs/user-guide/010-deploying/70-balena-deployment.md | Removed sidebar_position. |
| docs/user-guide/010-deploying/60-openremote-cli.md | Removed sidebar_position. |
| docs/user-guide/010-deploying/50-kubernetes.md | Removed sidebar_position. |
| docs/user-guide/010-deploying/40-aws-marketplace.md | Removed sidebar_position. |
| docs/user-guide/010-deploying/30-aws-cloudformation.md | Removed sidebar_position. |
| docs/user-guide/010-deploying/20-configuring-the-manager-ui.md | Added replacement “Configuring the Manager UI” doc under prefixed Deploying section. |
| docs/user-guide/010-deploying/10-custom-deployment.md | Removed sidebar_position; updated many links to prefixed dev guide docs. |
| docs/user-guide/010-deploying/category.json | Removed category position. |
| docs/tutorials/120-configure-mobile-app-behaviour.md | Removed sidebar_position; updated links to prefixed docs. |
| docs/tutorials/110-change-celsius-to-fahrenheit-with-flow.md | Removed sidebar_position. |
| docs/tutorials/100-simulating-data-in-attribute.md | Removed sidebar_position. |
| docs/tutorials/090-ota-firmware-updates-with-hawkbit.md | Removed sidebar_position. |
| docs/tutorials/080-auto-provision-devices-at-scale.md | Removed sidebar_position. |
| docs/tutorials/070-edge-gateway-secure-tunnel.md | Removed sidebar_position. |
| docs/tutorials/060-enterprise-identity-sso-rbac.md | Removed sidebar_position. |
| docs/tutorials/050-connect-modbus-devices.md | Removed sidebar_position. |
| docs/tutorials/040-receive-lorawan-sensor-data-from-chirpstack.md | Removed sidebar_position; updated links to prefixed agents-protocols docs. |
| docs/tutorials/030-connect-your-mqtt-client.md | Removed sidebar_position; updated Manager APIs links to prefixed doc. |
| docs/tutorials/020-open-weather-api-using-http-agent.md | Removed sidebar_position. |
| docs/tutorials/010-white-label-multi-tenant-iot-platform.md | Removed sidebar_position. |
| docs/developer-guide/160-frontend-testing.md | Added new Frontend Testing guide (Playwright-based). |
| docs/developer-guide/150-create-docker-machine-on-aws-ec2.md | Added new (unlisted) AWS EC2 docker-machine guide. |
| docs/developer-guide/140-working-on-the-mobile-consoles.md | Removed sidebar_position. |
| docs/developer-guide/130-working-on-maps.md | Removed sidebar_position; updated Geocoding link to prefixed user-guide path. |
| docs/developer-guide/120-adding-widgets-on-insights.md | Removed sidebar_position; updated gateway-tunnelling link to prefixed file. |
| docs/developer-guide/110-working-on-ui-and-apps.md | Removed sidebar_position; updated internal references to prefixed dev docs. |
| docs/developer-guide/100-system-administration.md | Removed sidebar_position; updated Metrics link to prefixed doc. |
| docs/developer-guide/090-external-services.md | Removed sidebar_position; updated links to prefixed user-guide/architecture docs. |
| docs/developer-guide/080-extensions.md | Removed sidebar_position. |
| docs/developer-guide/070-gateway-tunnelling-setup.md | Removed sidebar_position. |
| docs/developer-guide/060-licensing-guidelines-for-contributors.md | Removed sidebar_position. |
| docs/developer-guide/050-agent-protocol-spi.md | Removed sidebar_position. |
| docs/developer-guide/040-creating-a-custom-project.md | Removed sidebar_position; updated links to prefixed architecture/deploying docs. |
| docs/developer-guide/030-docker-compose-profiles.md | Removed sidebar_position; updated Setting up an IDE link to prefixed file. |
| docs/developer-guide/020-setting-up-an-ide.md | Removed sidebar_position; updated internal links to prefixed dev docs. |
| docs/developer-guide/010-preparing-the-environment.md | Removed sidebar_position. |
| docs/architecture/70-esp32-device.md | Removed sidebar_position; updated links to prefixed user-guide/architecture docs. |
| docs/architecture/60-apps-and-consoles.md | Removed sidebar_position. |
| docs/architecture/50-asset-location-tracking.md | Removed sidebar_position. |
| docs/architecture/40-asset-validation.md | Removed sidebar_position. |
| docs/architecture/30-security.md | Removed sidebar_position. |
| docs/architecture/20-manager-endpoints-and-file-paths.md | Removed sidebar_position; updated link to prefixed Deploying doc. |
| docs/architecture/10-overall-architecture.md | Removed sidebar_position. |
| docs/20-quick-start.md | Removed sidebar_position; updated “What next” links to prefixed docs. |
| docs/10-introduction.md | Removed sidebar_position; updated links to prefixed docs. |
Comments suppressed due to low confidence (2)
docs/user-guide/020-manager-ui/10-manager-ui.md:85
- This line still links to the old
agents-protocolspaths for Z-Wave and KNX. Those files were renumbered/moved under040-agents-protocols, so these links will be broken in the rendered docs.
docs/user-guide/110-anomaly-detection.md:40 - Grammar/wording issue introduced/retained on the modified line: “This accuracy…” and “build in” read incorrectly, and the sentence is missing a trailing period. This is user-facing documentation, so it’s worth fixing while touching the line.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Switch the bare URL link to the prefixed .md file-path form so it matches the repo convention and is validated as a file link at build.
1b02e66 to
adbbda3
Compare
wborn
approved these changes
Jul 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #164.
Move
/docs/ordering fromsidebar_positionfrontmatter to numeric filename/folder prefixes (increments of 10), so ordering is visible in the file tree.NN-reflecting current sidebar order.sidebar_positionfrontmatter and_category_.jsonposition.manager-ui/servicesfolder-index URLs with explicitslug.Docusaurus strips the number prefix from doc id/label/URL, so public URLs are unchanged (verified: original vs migrated permalinks diff is empty; production build passes with broken-link checking on).