Documentation Restructure Phase 2: Reorganization and Image Reference Fixes

[TechHutTV]

Documentation Restructure Phase 2: Reorganization and Image Reference Fixes

Overview

This PR implements a comprehensive reorganization of the NetBird documentation structure, moving content into a more logical hierarchy under the manage/ directory, fixing broken image references, and updating routing configurations to support the new structure.

🎯 Objectives

• Reorganize documentation into a clearer hierarchical structure
• Fix broken image references across all MDX files
• Update navigation and routing to reflect new structure
• Ensure all image assets are properly located and referenced

📋 Summary of Changes

Documentation Files Moved (30 files)

• Getting Started: 11 files moved from how-to/ and how-to/installation/ to getting-started/ and getting-started/install/
• Peers: 9 files moved to manage/peers/ and subdirectories
• Networks: 4 files moved to manage/networks/ and subdirectories
• Network Routes: 4 files moved to manage/network-routes/
• Control Center: 1 file moved to manage/control-center/

Documentation Files Modified (20 files)

• Updated image paths in existing files to reflect new structure
• Fixed broken image references
• Updated internal links

Image Files Reorganized (231+ files)

• Control Center: 3 images moved
• Network Routes: 30+ images moved
• Networks: 60+ images moved
• Peers: 100+ images moved/reorganized
• New images: 20+ added

📁 Major Structural Changes

Documentation Reorganization

Getting Started Section

Moved from how-to/ to getting-started/:

• how-to/cli.mdx → getting-started/cli.mdx
• how-to/getting-started.mdx → getting-started/index.mdx

Moved from how-to/installation/ to getting-started/install/:

• how-to/installation/index.mdx → getting-started/install/index.mdx
• how-to/installation/docker.mdx → getting-started/install/docker.mdx
• how-to/installation/linux.mdx → getting-started/install/linux.mdx
• how-to/installation/macos.mdx → getting-started/install/macos.mdx
• how-to/installation/mobile.mdx → getting-started/install/mobile.mdx
• how-to/installation/opnsense.mdx → getting-started/install/opnsense.mdx
• how-to/installation/pfsense.mdx → getting-started/install/pfsense.mdx
• how-to/installation/synology.mdx → getting-started/install/synology.mdx
• how-to/installation/windows.mdx → getting-started/install/windows.mdx

Peers Section

Moved from how-to/ to manage/peers/:

• how-to/approve-peers.mdx → manage/peers/approve-peers.mdx
• how-to/browser-client.mdx → manage/peers/browser-client.mdx
• how-to/lazy-connection.mdx → manage/peers/lazy-connection.mdx
• how-to/register-machines-using-setup-keys.mdx → manage/peers/setup-keys.mdx
• how-to/ssh.mdx → manage/peers/ssh.mdx
• how-to/add-machines-to-your-network.mdx → manage/peers/add-machines-to-your-network.mdx
• how-to/db-workload-migration.mdx → manage/peers/connect-site-to-site/db-workload-migration.mdx

Moved from how-to/ to manage/peers/access-infrastructure/:

• how-to/access-internal-resources-from-autoscaled-environments.mdx → manage/peers/access-infrastructure/access-internal-resources-from-autoscaled-environments.mdx
• how-to/peer-approval-for-remote-worker-access.mdx → manage/peers/access-infrastructure/peer-approval-for-remote-worker-access.mdx
• how-to/secure-remote-webserver-access.mdx → manage/peers/access-infrastructure/secure-remote-webserver-access.mdx
• how-to/setup-keys-add-servers-to-network.mdx → manage/peers/access-infrastructure/setup-keys-add-servers-to-network.mdx

Networks Section

Moved from how-to/ to manage/networks/:

• how-to/networks.mdx → manage/networks/index.mdx
• how-to/accessing-entire-domains-within-networks.mdx → manage/networks/accessing-entire-domains-within-networks.mdx
• how-to/accessing-restricted-domain-resources.mdx → manage/networks/accessing-restricted-domain-resources.mdx
• how-to/routing-traffic-to-multiple-resources.mdx → manage/networks/routing-traffic-to-multiple-resources.mdx

Moved from how-to/ to manage/networks/homelab/:

• how-to/access-home-network.mdx → manage/networks/homelab/access-home-network.mdx

Network Routes Section

Moved from how-to/ to manage/network-routes/:

• how-to/configuring-default-routes-for-internet-traffic.mdx → manage/network-routes/configuring-default-routes-for-internet-traffic.mdx
• how-to/configuring-routes-with-access-control.mdx → manage/network-routes/configuring-routes-with-access-control.mdx
• how-to/resolve-overlapping-routes.mdx → manage/network-routes/resolve-overlapping-routes.mdx
• how-to/routing-traffic-to-private-networks.mdx → manage/network-routes/routing-traffic-to-private-networks.mdx

Control Center Section

Moved from how-to/ to manage/control-center/:

• how-to/control-center.mdx → manage/control-center/index.mdx

Modified Files (Image Path Updates)

• about-netbird/browser-client-architecture.mdx
• about-netbird/faq.mdx
• about-netbird/how-netbird-works.mdx
• about-netbird/other.mdx
• how-to/acronis-netbird-integration.mdx
• how-to/activity-event-streaming.mdx
• how-to/enforce-periodic-user-authentication.mdx
• how-to/examples.mdx
• how-to/intune-netbird-integration.mdx
• how-to/kubernetes-operator.mdx
• how-to/stream-activity-to-datadog.mdx
• how-to/traffic-events-logging.mdx
• how-to/troubleshooting-client.mdx
• manage/access-control/index.mdx
• manage/access-control/manage-network-access.mdx
• manage/access-control/posture-checks/connecting-from-the-office.mdx
• selfhosted/identity-providers.mdx
• selfhosted/self-hosted-vs-cloud-netbird.mdx
• use-cases/distributed-multi-cloud-ai-argocd-microk8s-vllm.mdx

Image Assets Reorganization

Reorganized image directories (231+ image files moved):

Control Center Images:

• how-to-guides/control-center/control-center-groups-view.png → manage/control-center/control-center-groups-view.png
• how-to-guides/control-center/control-center-network-view.png → manage/control-center/control-center-network-view.png
• how-to-guides/control-center/control-center-peer-view.png → manage/control-center/control-center-peer-view.png

Network Routes Images (30+ files):

• All network routes images moved from how-to-guides/ to manage/network-routes/
• Exit node images: exit-node-auto-apply.png, netbird-peers-add-exit-node.png, netbird-peers-routing-peer-exit-node.png
• Route creation images: netbird-network-routes-create.png, netbird-network-routes-create-groups.png, netbird-network-routes-create-ha.png
• ACL and policy images: network-acl-create-policy.png, network-route-acl.png, network-route-acl-saved.png
• Routing traffic images moved to manage/network-routes/routing-traffic-to-private-networks/

Networks Images (60+ files):

• Domain access images (20 files) moved to manage/networks/accessing-entire-domains-within-networks/
• Restricted domain images (13 files) moved to manage/networks/accessing-restricted-domain-resources/
• Network management images moved to manage/networks/
• Homelab images (7 files) moved to manage/networks/homelab/

Peers Images:

• Access infrastructure images moved to manage/peers/access-infrastructure/
• Site-to-site migration images moved to manage/peers/connect-site-to-site/
• Browser client images moved to manage/peers/browser-client/
• SSH images moved to manage/peers/ssh/
• New peer images added: add-new-peer-empty.png, add-new-peer-popup.png, add-setup-key.png, local-peer.png, remote-peer.png, netbird-peer-page.png, setup-keys.png, and more

New Image Additions:

• manage/networks/netbird-network-routes.png
• manage/access-control/posture-checks/connecting-from-the-office/route-office-subnet-posturecheck.png (fixed broken reference)

🔧 Technical Changes

Configuration Updates

next.config.mjs:

• Updated routing and rewrites to support new documentation structure
• Added redirects for moved content to maintain backward compatibility
• Enhanced routing logic for improved navigation

src/components/NavigationDocs.jsx:

• Updated navigation structure to reflect new organization
• Adjusted navigation paths for reorganized content

Image Reference Fixes

Comprehensive image audit:

• Scanned all 115 MDX files for image references
• Identified and fixed 1 broken image reference:
  • Fixed missing route-office-subnet-posturecheck.png in connecting-from-the-office.mdx
  • Copied image from how-to-guides/ to correct location in manage/access-control/posture-checks/connecting-from-the-office/

Image path updates:

• Updated all image references to use consistent /docs-static/img/ paths
• Ensured all referenced images exist in the correct locations
• Standardized image naming conventions

📊 Statistics

• Files changed: 252 files
• MDX files moved: 30 documentation files reorganized
• MDX files modified: 20+ files with updated image paths
• Images reorganized: 231+ image files moved/consolidated
• New images added: 20+ new screenshots and diagrams
• Broken references fixed: 1 image reference corrected
• Lines changed: +479 insertions, -315 deletions

🗂️ File Structure Changes

New Directory Structure

getting-started/
├── cli.mdx
├── index.mdx
└── install/
    ├── index.mdx
    ├── docker.mdx
    ├── linux.mdx
    ├── macos.mdx
    ├── mobile.mdx
    ├── opnsense.mdx
    ├── pfsense.mdx
    ├── synology.mdx
    └── windows.mdx

manage/
├── access-control/
│   ├── index.mdx
│   ├── manage-network-access.mdx
│   └── posture-checks/
│       └── connecting-from-the-office.mdx
├── control-center/
│   └── index.mdx
├── network-routes/
│   ├── configuring-default-routes-for-internet-traffic.mdx
│   ├── configuring-routes-with-access-control.mdx
│   ├── resolve-overlapping-routes.mdx
│   └── routing-traffic-to-private-networks.mdx
├── networks/
│   ├── index.mdx
│   ├── accessing-entire-domains-within-networks.mdx
│   ├── accessing-restricted-domain-resources.mdx
│   ├── routing-traffic-to-multiple-resources.mdx
│   └── homelab/
│       └── access-home-network.mdx
└── peers/
    ├── approve-peers.mdx
    ├── browser-client.mdx
    ├── lazy-connection.mdx
    ├── setup-keys.mdx
    ├── ssh.mdx
    ├── add-machines-to-your-network.mdx
    ├── access-infrastructure/
    │   ├── secure-remote-webserver-access.mdx
    │   ├── peer-approval-for-remote-worker-access.mdx
    │   ├── access-internal-resources-from-autoscaled-environments.mdx
    │   └── setup-keys-add-servers-to-network.mdx
    └── connect-site-to-site/
        └── db-workload-migration.mdx

✅ Quality Assurance

• Image validation: All image references verified and working
• Link integrity: All internal documentation links updated
• Navigation: Navigation structure updated to reflect new organization
• Routing: All routes properly configured in next.config.mjs
• Backward compatibility: Redirects added for moved content

🚀 Impact

User Experience

• Clearer documentation hierarchy makes it easier to find relevant content
• Better organization of peer, network, and access control documentation
• Improved navigation structure

Maintenance

• More logical file organization reduces maintenance overhead
• Consistent image path structure simplifies future updates
• Clear separation of concerns (manage vs. how-to)

📝 Migration Notes

• Old URLs will redirect to new locations via next.config.mjs
• Image paths have been updated throughout all documentation
• Navigation has been updated to reflect new structure

🔍 Testing

• All image references verified
• Navigation structure tested
• Routing and redirects verified
• Documentation links checked
• Image assets confirmed in correct locations

📚 Related Documentation

This PR is part of the documentation restructure initiative to improve the overall organization and maintainability of the NetBird documentation.

---

Note: This PR includes comprehensive changes to documentation structure. Reviewers should pay special attention to:

1. Image path updates and asset locations
2. Navigation structure changes
3. Routing configuration updates
4. Content organization and hierarchy