Repository navigation
NOISSUE - Fix dev-guide nav order and separate legacy services in sidebar - #182
Merged
Merged
Conversation
Reorder dev-guide top-level nav: Introduction and Getting Started first, Agent moved next to Edge (they're a matched pair — Edge is literally "deploy Agent at the edge"), per feedback that Agent showing up right after Introduction made no sense. Split the Services sidebar into current services (consumers, readers, alarms, reports, rules-engine) and a separated "Legacy (superseded by Atom)" group (auth, users, clients, channels, provision, bootstrap, notifications). Those 7 pages already carry an in-page warning callout saying the service no longer exists, but the flat sidebar gave no way to tell live from dead without opening each one.
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
magistrala-docs | 0890c96 | Commit Preview URL Branch Preview URL |
Sep 02 2026, 11:47 AM |
dborovcanin
requested changes
Sep 1, 2026
dborovcanin
left a comment
dborovcanin
left a comment
Contributor
There was a problem hiding this comment.
Let's remove legacy services completely to keep docs flat and simple and not confusing.
Per review feedback: keep docs flat and simple rather than confusing, so delete the 7 pages describing services that no longer exist (auth, users, clients, channels, provision, bootstrap, notifications) instead of just splitting them into a separate "Legacy" sidebar group. Also fixed every other page that linked to one of these now-deleted pages, so nothing in the site 404s: - user-guide/bootstrap.mdx: dropped its "see the Bootstrap dev-guide page" cross-reference, since that page is gone. - dev-guide/authorization.mdx: repointed its "see Auth" callout link to the Overview page (entities.mdx) instead, since it describes Atom's current entity model. - dev-guide/edge.mdx, extensions/twins.mdx, dev-tools/authentication.mdx: these already-legacy pages referenced bootstrap/provision by markdown reference-link ([text][ref]); converted those to plain text and removed the now-dead reference-link definitions rather than rewriting the surrounding legacy content. - dev-guide/services/consumers.mdx: its own callout linked to Notifications to explain where invitation emails come from now; removed the dead link, kept the (already correct) explanation that it's Atom, not this package.
dborovcanin
requested changes
Sep 1, 2026
dborovcanin
left a comment
dborovcanin
left a comment
Contributor
There was a problem hiding this comment.
@fbugarski Bootstrap is not a legacy and should stay in docs.
…pages
Per review feedback: Bootstrap is still a real, current concept
(devices still bootstrap; it just runs merged into the atom-bootstrap
deployment now), unlike auth/users/clients/channels/provision/
notifications which genuinely no longer exist. Restored
dev-guide/services/bootstrap.mdx, added it back to
services/meta.json, and restored the two links to it that were
removed when it was deleted (user-guide/bootstrap.mdx's
"see the Bootstrap dev-guide page" cross-reference, and edge.mdx's
bootstrap-server mentions).
While restoring it, verified its content against the actual current
bootstrap package (magistrala/bootstrap) rather than just undoing the
deletion as-is, since it was written before the domain->workspace and
client->device renames:
- Fixed all `/{domain_id}/clients/...` config/profile/enrollment
paths to the real registered routes, `/{workspaceID}/devices/...`
(confirmed against bootstrap/api/transport.go's route tree).
- Fixed CLI examples' `<domain_id>` arg to `<workspace_id>`,
matching the actual `cli/bootstrap.go` Cobra command Use strings.
- Removed a "kept for compatibility" claim about the old
`/clients/configs` path — no such alias route exists; it was
renamed, not aliased.
- Found something bigger while checking this: the device-facing
"Device Bootstrap"/"Secure Bootstrap" sections describe a static
AES-key, single-GET-request flow that no longer matches the code.
The actual routes are now a two-step POST challenge/configuration
handshake with server/device nonces (bootstrap/device_bootstrap.go,
device_crypto.go). Rather than guess at the new wire format, added
a callout flagging that section as needing a rewrite from someone
who knows the new protocol.
# Conflicts: # content/docs/dev-guide/services/bootstrap.mdx
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
2 participants
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.
What type of PR is this?
This is a documentation update because it fixes the dev-guide sidebar navigation order and structure.
What does this do?
Reorder dev-guide top-level nav: Introduction and Getting Started first, Agent moved next to Edge (they're a matched pair — Edge is literally "deploy Agent at the edge"), per feedback that Agent showing up right after Introduction made no sense.
Split the Services sidebar into current services (consumers, readers, alarms, reports, rules-engine) and a separated "Legacy (superseded by Atom)" group (auth, users, clients, channels, provision, bootstrap, notifications). Those 7 pages already carry an in-page warning callout saying the service no longer exists, but the flat sidebar gave no way to tell live from dead without opening each one.
Which issue(s) does this PR fix/relate to?
Have you included tests for your changes?
Not applicable — this only reorders/regroups existing pages in meta.json navigation config, no content changes. Verified both meta.json files are valid JSON and every referenced page slug still exists.
Did you document any new/modified features?
N/A — this is a structural/navigation fix, not new content.
Notes
None.