Restructuring Phase 3 - #492
Merged
Merged
Conversation
TechHutTV
marked this pull request as ready for review
November 24, 2025 13:38
braginini
approved these changes
Nov 24, 2025
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.
Documentation Reorganization: Restructure Content into Logical
/manage/HierarchyOverview
This PR implements a comprehensive reorganization of the NetBird documentation site, restructuring content from a flat
/how-to/directory into a more intuitive, hierarchical/manage/structure. This reorganization improves content discoverability, maintains logical grouping of related topics, and ensures all internal links, images, and navigation remain functional.Motivation
The previous documentation structure had all content in a single
/how-to/directory, making it difficult to navigate and understand relationships between topics. This reorganization groups related content into logical categories under/manage/, creating a clearer information architecture that better reflects how users interact with NetBird's features.Major Changes
1. Content Reorganization
New Directory Structure
Content has been reorganized into the following structure:
/manage/peers/- Peer management and configurationaccess-infrastructure/- Infrastructure access scenariossite-to-site/- Site-to-site connectivity/manage/networks/- Network configuration and managementhomelab/- Home network scenarios/manage/network-routes/- Network routing configuration/manage/team/- Team and user managementidp-sync/- Identity provider synchronization (Okta, Microsoft Entra ID, Google Workspace, JumpCloud, Keycloak)/manage/activity/- Activity monitoring and loggingevent-streaming/- Event streaming integrations (Datadog, Amazon S3, Amazon Firehose, SentinelOne Data Lake, Generic HTTP)/manage/dns/- DNS configuration/manage/control-center/- Control center overview/use-cases/- Use case examples and scenariosFiles Moved
Peers (11 files):
add-machines-to-your-network.mdxapprove-peers.mdxbrowser-client.mdxregister-machines-using-setup-keys.mdxssh.mdxlazy-connection.mdxaccess-infrastructure/access-internal-resources-from-autoscaled-environments.mdxaccess-infrastructure/peer-approval-for-remote-worker-access.mdxaccess-infrastructure/secure-remote-webserver-access.mdxaccess-infrastructure/setup-keys-add-servers-to-network.mdxsite-to-site/db-workload-migration.mdxNetworks (5 files):
index.mdx(networks concept)accessing-entire-domains-within-networks.mdxaccessing-restricted-domain-resources.mdxrouting-traffic-to-multiple-resources.mdxhomelab/access-home-network.mdxNetwork Routes (4 files):
routing-traffic-to-private-networks.mdxconfiguring-default-routes-for-internet-traffic.mdxconfiguring-routes-with-access-control.mdxresolve-overlapping-routes.mdxTeam (10 files):
add-users-to-your-network.mdxapprove-users.mdxauto-offboard-users.mdxsingle-sign-on.mdxidp-sync/index.mdxidp-sync/microsoft-entra-id-sync.mdxidp-sync/okta-sync.mdxidp-sync/google-workspace-sync.mdxidp-sync/jumpcloud-sync.mdxidp-sync/keycloak-sync.mdxActivity (8 files):
index.mdx(audit events logging)traffic-events-logging.mdxevent-streaming/index.mdxevent-streaming/datadog.mdx(renamed fromstream-activity-to-datadog.mdx)event-streaming/amazon-s3.mdx(renamed fromstream-activity-to-amazon-s3.mdx)event-streaming/amazon-firehose.mdx(renamed fromstream-activity-to-amazon-firehose.mdx)event-streaming/sentinelone-data-lake.mdx(renamed fromstream-activity-to-sentinelone-data-lake.mdx)event-streaming/generic-http.mdx(renamed fromstream-activity-to-generic-http.mdx)Other:
control-center.mdx→manage/control-center/index.mdxmanage-dns-in-your-network.mdx→manage/dns/index.mdxexamples.mdx→use-cases/examples.mdxrouting-peers-and-kubernetes.mdx→use-cases/routing-peers-and-kubernetes.mdxOld vs New URL Map
The move touched every public-facing URL under
/how-to/. The most frequently referenced paths now resolve to the following destinations (redirects innext.config.mjsguarantee backward compatibility):Peers
/how-to/add-machines-to-your-network→/manage/peers/add-machines-to-your-network/how-to/approve-peers→/manage/peers/approve-peers/how-to/browser-client→/manage/peers/browser-client/how-to/register-machines-using-setup-keys→/manage/peers/register-machines-using-setup-keys/how-to/ssh→/manage/peers/ssh/how-to/lazy-connection→/manage/peers/lazy-connection/how-to/access-internal-resources-from-autoscaled-environments→/manage/peers/access-infrastructure/access-internal-resources-from-autoscaled-environments/how-to/peer-approval-for-remote-worker-access→/manage/peers/access-infrastructure/peer-approval-for-remote-worker-access/how-to/secure-remote-webserver-access→/manage/peers/access-infrastructure/secure-remote-webserver-access/how-to/setup-keys-add-servers-to-network→/manage/peers/access-infrastructure/setup-keys-add-servers-to-network/how-to/db-workload-migration→/manage/peers/site-to-site/db-workload-migrationNetworks
/how-to/networksand/how-to/networks-concept→/manage/networks/how-to/accessing-entire-domains-within-networks→/manage/networks/accessing-entire-domains-within-networks/how-to/accessing-restricted-domain-resources→/manage/networks/accessing-restricted-domain-resources/how-to/routing-traffic-to-multiple-resources→/manage/networks/routing-traffic-to-multiple-resources/how-to/access-home-network→/manage/networks/homelab/access-home-networkNetwork Routes
/how-to/routing-traffic-to-private-networks→/manage/network-routes/routing-traffic-to-private-networks/how-to/configuring-default-routes-for-internet-traffic→/manage/network-routes/configuring-default-routes-for-internet-traffic/how-to/configuring-routes-with-access-control→/manage/network-routes/configuring-routes-with-access-control/how-to/resolve-overlapping-routes→/manage/network-routes/resolve-overlapping-routesControl Center & DNS
/how-to/control-center→/manage/control-center/how-to/manage-dns-in-your-networkand/docs/how-to-guides/nameservers→/manage/dnsTeam
/how-to/add-users-to-your-network→/manage/team/add-users-to-your-network/how-to/approve-users→/manage/team/approve-users/how-to/auto-offboard-users→/manage/team/auto-offboard-users/how-to/single-sign-on→/manage/team/single-sign-on/how-to/idp-sync→/manage/team/idp-sync/how-to/microsoft-entra-id-sync→/manage/team/idp-sync/microsoft-entra-id-sync/how-to/okta-sync→/manage/team/idp-sync/okta-sync/how-to/google-workspace-sync→/manage/team/idp-sync/google-workspace-sync/how-to/jumpcloud-sync→/manage/team/idp-sync/jumpcloud-sync/how-to/keycloak-sync→/manage/team/idp-sync/keycloak-syncActivity & Event Streaming
/how-to/audit-events-logging→/manage/activity/how-to/traffic-events-logging→/manage/activity/traffic-events-logging/how-to/activity-event-streaming→/manage/activity/event-streaming/how-to/stream-activity-to-datadog→/manage/activity/event-streaming/datadog/how-to/stream-activity-to-amazon-s3→/manage/activity/event-streaming/amazon-s3/how-to/stream-activity-to-amazon-firehose→/manage/activity/event-streaming/amazon-firehose/how-to/stream-activity-to-sentinelone-data-lake→/manage/activity/event-streaming/sentinelone-data-lake/how-to/stream-activity-to-generic-http→/manage/activity/event-streaming/generic-httpUse Cases
/how-to/examples→/use-cases/examples/how-to/routing-peers-and-kubernetes→/use-cases/routing-peers-and-kubernetes2. Image Asset Reorganization
All images referenced by moved documentation files have been reorganized to match the new content structure:
/public/docs-static/img/manage/peers/with subdirectories matching content structure/public/docs-static/img/manage/networks/with appropriate subdirectories/public/docs-static/img/manage/network-routes/organized by topic/public/docs-static/img/manage/team/with subdirectories for idp-sync and single-sign-on/public/docs-static/img/manage/activity/with subdirectories for event-streaming integrations/public/docs-static/img/manage/dns//public/docs-static/img/manage/control-center//public/docs-static/img/use-cases/Total images reorganized: 200+ image files moved and organized into logical directory structures
Old → New image bases
/public/docs-static/img/how-to-guides/<peer-topic>/…→/public/docs-static/img/manage/peers/<peer-topic>/…/public/docs-static/img/how-to-guides/networks*/…→/public/docs-static/img/manage/networks/<sub-topic>/…/public/docs-static/img/how-to-guides/network-routes*/…→/public/docs-static/img/manage/network-routes/<sub-topic>/…/public/docs-static/img/how-to-guides/<idp-sync|single-sign-on>/…→/public/docs-static/img/manage/team/<sub-folder>/…/public/docs-static/img/how-to-guides/activity*/…→/public/docs-static/img/manage/activity/<event-streaming|traffic-events>/…/public/docs-static/img/how-to-guides/control-center/…→/public/docs-static/img/manage/control-center/…/public/docs-static/img/how-to-guides/dns*/…→/public/docs-static/img/manage/dns/…/public/docs-static/img/examples/…→/public/docs-static/img/use-cases/examples/…During the move, each
.mdxfile’s<img src>attributes were updated to match the new directory, ensuring every asset has a single authoritative location that mirrors the documentation hierarchy.3. Link Updates
Internal Links
.mdxfilesNavigationDocs.jsx,AnnouncementBannerProvider.jsx)External Links
docs.netbird.iolinks to point to new paths4. Navigation Updates
Updated
src/components/NavigationDocs.jsxto reflect the new structure:/how-to/to/manage/peers//manage/networks//manage/team//manage/activity/5. Redirect Configuration
Added 50+ permanent redirects in
next.config.mjsto ensure backward compatibility:All old
/how-to/paths now redirect to their new/manage/locations, ensuring existing bookmarks and external links continue to work.6. File Renaming
Several files were renamed for consistency:
stream-activity-to-*.mdx→*.mdx(e.g.,stream-activity-to-datadog.mdx→datadog.mdx)index.mdxfiles for cleaner URLsTechnical Details
Image Path Updates
/docs-static/img/how-to-guides/paths to new/docs-static/img/manage/pathsenforce-periodic-user-authentication.mdxLink Validation
.mdxfilesFile Structure Consistency
Testing
Breaking Changes
None - All old URLs redirect to new locations, maintaining full backward compatibility.
Migration Notes
For developers:
/how-to/paths will automatically redirect to new/manage/pathsFiles Changed
.mdxfiles - Content files moved and links updatednext.config.mjs- Added 50+ redirect rulessrc/components/NavigationDocs.jsx- Updated navigation structuresrc/components/announcement-banner/AnnouncementBannerProvider.jsx- Updated link.mdxfiles - Updated cross-referencesBenefits
Next Steps
Note: This is a comprehensive reorganization that touches many files. All changes have been verified, and the site maintains full backward compatibility through redirects.