Skip to main content

TalkOps Documentation: Docusaurus Sidebar Architecture & Structure

Comprehensive Research-Based Design Guide Date: January 12, 2026

EXECUTIVE SUMMARY​

Based on extensive research on Docusaurus best practices, SaaS agent documentation patterns, MCP (Model Context Protocol) architecture, and extensible platform documentation, I've designed a scalable sidebar structure that accommodates current features while remaining extensible for future growth.

Key Insight: Documentation should mirror your product architecture (agents, MCPs, configurations) while maintaining cognitive balance—too deep hierarchies hurt discoverability, but single-level navigation doesn't scale.

Overview: 3-Tier Architecture​

TalkOps Documentation
├── Getting Started (Quick wins)
├── Core Concepts (Understanding)
├── Agents Library (Feature-focused)
│   ├── Infrastructure Agent
│   ├── Application Agent
│   ├── Monitoring Agent
│   └── SRE Agent
├── Integrations (MCP Servers & Extensions)
│   ├── Cloud Integration Servers
│   ├── Monitoring & Observability
│   └── CI/CD & GitOps
├── API & Integration (Developer tools)
├── Configuration & Administration
└── Troubleshooting & Advanced

Rationale:

  • Tier 1: Onboarding paths (not overwhelming)
  • Tier 2: Mental models (how things work together)
  • Tier 3: Feature deep-dives (each agent, each MCP server)
  • Tier 4: Technical details (APIs, advanced config)

COMPLETE SIDEBAR CONFIGURATION​

sidebars.js Structure​

import type {SidebarsConfig} from '@docusaurus/types';

const sidebars: SidebarsConfig = {
  // Main documentation sidebar
  docSidebar: [
    'index', // TalkOps Overview
    
    {
      type: 'category',
      label: 'Getting Started',
      collapsed: false,
      items: [
        'getting-started/quickstart',
        'getting-started/installation',
        'getting-started/first-deployment',
        'getting-started/basic-concepts',
      ],
    },

    {
      type: 'category',
      label: 'Core Concepts',
      collapsed: false,
      link: {
        type: 'generated-index',
        title: 'Understanding TalkOps Architecture',
        description: 'Learn how TalkOps agents, orchestration, and governance work together',
      },
      items: [
        'concepts/agent-architecture',
        'concepts/multi-agent-orchestration',
        'concepts/governance-guardrails',
        'concepts/mcp-integration',
        'concepts/conversational-interface',
      ],
    },

    {
      type: 'category',
      label: 'Agents',
      collapsed: false,
      link: {
        type: 'generated-index',
        title: 'Available Agents',
        description: 'Detailed documentation for each specialized agent',
      },
      items: [
        {
          type: 'category',
          label: 'Infrastructure Agent',
          collapsed: true,
          link: {
            type: 'doc',
            id: 'agents/infrastructure/overview',
          },
          items: [
            'agents/infrastructure/capabilities',
            'agents/infrastructure/configuration',
            'agents/infrastructure/examples',
            'agents/infrastructure/troubleshooting',
          ],
        },

        {
          type: 'category',
          label: 'Application Agent',
          collapsed: true,
          link: {
            type: 'doc',
            id: 'agents/application/overview',
          },
          items: [
            'agents/application/capabilities',
            'agents/application/configuration',
            'agents/application/examples',
            'agents/application/troubleshooting',
          ],
        },

        {
          type: 'category',
          label: 'Monitoring Agent',
          collapsed: true,
          link: {
            type: 'doc',
            id: 'agents/monitoring/overview',
          },
          items: [
            'agents/monitoring/capabilities',
            'agents/monitoring/configuration',
            'agents/monitoring/examples',
            'agents/monitoring/troubleshooting',
          ],
        },

        {
          type: 'category',
          label: 'SRE Agent',
          collapsed: true,
          link: {
            type: 'doc',
            id: 'agents/sre/overview',
          },
          items: [
            'agents/sre/capabilities',
            'agents/sre/configuration',
            'agents/sre/examples',
            'agents/sre/troubleshooting',
          ],
        },
      ],
    },

    {
      type: 'category',
      label: 'Integrations & MCP Servers',
      collapsed: false,
      link: {
        type: 'generated-index',
        title: 'MCP Servers & Integrations',
        description: 'Extend TalkOps with MCP servers for cloud, monitoring, and CI/CD',
      },
      items: [
        'integrations/mcp-overview',
        'integrations/how-to-add-mcp',

        {
          type: 'category',
          label: 'Cloud Integrations',
          collapsed: true,
          items: [
            'integrations/cloud/aws-mcp',
            'integrations/cloud/azure-mcp',
            'integrations/cloud/gcp-mcp',
            'integrations/cloud/kubernetes-mcp',
          ],
        },

        {
          type: 'category',
          label: 'Monitoring & Observability',
          collapsed: true,
          items: [
            'integrations/monitoring/prometheus-mcp',
            'integrations/monitoring/datadog-mcp',
            'integrations/monitoring/grafana-mcp',
            'integrations/monitoring/splunk-mcp',
          ],
        },

        {
          type: 'category',
          label: 'CI/CD & GitOps',
          collapsed: true,
          items: [
            'integrations/cicd/jenkins-mcp',
            'integrations/cicd/argocd-mcp',
            'integrations/cicd/github-actions-mcp',
            'integrations/cicd/gitlab-ci-mcp',
          ],
        },

        {
          type: 'category',
          label: 'Communication & Alerting',
          collapsed: true,
          items: [
            'integrations/communication/slack-mcp',
            'integrations/communication/pagerduty-mcp',
            'integrations/communication/opsgenie-mcp',
          ],
        },
      ],
    },

    {
      type: 'category',
      label: 'Configuration',
      collapsed: true,
      link: {
        type: 'generated-index',
        title: 'Configuration & Setup',
        description: 'Configure agents, guardrails, permissions, and deployment',
      },
      items: [
        'configuration/agent-configuration',
        'configuration/guardrails-setup',
        'configuration/permissions-rbac',
        'configuration/deployment-options',
        'configuration/environment-variables',
        'configuration/custom-agents',
      ],
    },

    {
      type: 'category',
      label: 'API & Integration',
      collapsed: true,
      link: {
        type: 'generated-index',
        title: 'APIs & Developer Integration',
        description: 'REST APIs, A2A protocol, webhooks, and custom integration patterns',
      },
      items: [
        'api/overview',
        'api/rest-api',
        'api/a2a-protocol',
        'api/webhooks',
        'api/authentication',
        'api/rate-limiting',
        'api/custom-tools',
      ],
    },

    {
      type: 'category',
      label: 'Administration',
      collapsed: true,
      link: {
        type: 'generated-index',
        title: 'Administration & Management',
        description: 'User management, audit logs, compliance, and enterprise features',
      },
      items: [
        'administration/user-management',
        'administration/audit-logging',
        'administration/compliance',
        'administration/security',
        'administration/monitoring-talkops',
        'administration/backup-recovery',
      ],
    },

    {
      type: 'category',
      label: 'Troubleshooting & Advanced',
      collapsed: true,
      link: {
        type: 'generated-index',
        title: 'Troubleshooting & Advanced Topics',
        description: 'Debugging, performance optimization, and advanced use cases',
      },
      items: [
        'troubleshooting/common-issues',
        'troubleshooting/debugging-agents',
        'troubleshooting/performance-optimization',
        'troubleshooting/logs-telemetry',
        'advanced/custom-frameworks',
        'advanced/production-deployment',
      ],
    },

    {
      type: 'category',
      label: 'References',
      collapsed: true,
      items: [
        'reference/glossary',
        'reference/architecture-diagram',
        'reference/security-whitepaper',
        'reference/release-notes',
        'reference/faq',
      ],
    },
  ],
};

export default sidebars;

DETAILED SECTION BREAKDOWN​

1. GETTING STARTED (Non-Collapsible)​

Purpose: Quick wins for users onboarding Audience: New users, first-time setup

Getting Started/
├── Quickstart (5-min setup)
├── Installation (step-by-step)
├── First Deployment (your first agent task)
└── Basic Concepts (key mental models)

Why non-collapsible: Users need this visible immediately. Collapsed categories harm discoverability for onboarding.

Key Files:

  • getting-started/quickstart.md - "Set up TalkOps in 5 minutes"
  • getting-started/installation.md - Docker/K8s/local setup
  • getting-started/first-deployment.md - Deploy and execute first task
  • getting-started/basic-concepts.md - Infrastructure Agent, orchestration, governance

2. CORE CONCEPTS (Non-Collapsible)​

Purpose: Mental models before diving into features Audience: Users who need to understand HOW before using WHAT

Core Concepts/
├── Agent Architecture (supervisor, state, DAG)
├── Multi-Agent Orchestration (LangGraph model)
├── Governance & Guardrails (safety model)
├── MCP Integration (extensibility)
└── Conversational Interface (NLP + intent)

3. AGENTS LIBRARY (Collapsible, Hierarchical)​

Purpose: In-depth docs for each specialized agent Audience: Users implementing specific agents

Agents/
├── Infrastructure Agent (5 pages each)
├── Application Agent (5 pages each)
├── Monitoring Agent (5 pages each)
└── SRE Agent (5 pages each)

Pattern per agent:

  1. Overview - What this agent does, when to use it
  2. Capabilities - Exact actions it can perform
  3. Configuration - YAML/JSON config required
  4. Examples - Copy-paste ready scenarios
  5. Troubleshooting - Common errors & fixes

4. INTEGRATIONS & MCP SERVERS (Collapsible, Grouped by Category)​

Purpose: Help users integrate with external systems via MCP Audience: DevOps engineers, platform engineers

Integrations/
├── MCP Overview (what is MCP, why it matters)
├── How to Add MCP Servers (developer guide)
├── Cloud Integrations
│   ├── AWS MCP
│   ├── Azure MCP
│   ├── GCP MCP
│   └── Kubernetes MCP
├── Monitoring & Observability
│   ├── Prometheus MCP
│   ├── Datadog MCP
│   ├── Grafana MCP
│   └── Splunk MCP
├── CI/CD & GitOps
│   ├── Jenkins MCP
│   ├── ArgoCD MCP
│   ├── GitHub Actions MCP
│   └── GitLab CI MCP
└── Communication & Alerting
    ├── Slack MCP
    ├── PagerDuty MCP
    └── Opsgenie MCP

Extensibility Pattern:

  • New cloud provider? Create integrations/cloud/[new-provider]-mcp.md
  • New monitoring tool? Add to integrations/monitoring/
  • Sidebar auto-updates with new files

FILE STRUCTURE ON DISK​

docs/
├── _category_.json (root category metadata)
├── index.md (TalkOps Overview)
│
├── getting-started/
│   ├── _category_.json
│   ├── quickstart.md
│   ├── installation.md
│   ├── first-deployment.md
│   └── basic-concepts.md
│
├── concepts/
│   ├── _category_.json
│   ├── agent-architecture.md
│   ├── multi-agent-orchestration.md
│   ├── governance-guardrails.md
│   ├── mcp-integration.md
│   └── conversational-interface.md
│
├── agents/
│   ├── _category_.json
│   ├── infrastructure/
│   │   ├── _category_.json
│   │   ├── overview.md
│   │   ├── capabilities.md
│   │   ├── configuration.md
│   │   ├── examples.md
│   │   └── troubleshooting.md
│   ├── application/
│   │   └── [same structure]
│   ├── monitoring/
│   │   └── [same structure]
│   └── sre/
│       └── [same structure]
│
├── integrations/
│   ├── _category_.json
│   ├── mcp-overview.md
│   ├── how-to-add-mcp.md
│   ├── cloud/
│   │   ├── _category_.json
│   │   ├── aws-mcp.md
│   │   ├── azure-mcp.md
│   │   ├── gcp-mcp.md
│   │   └── kubernetes-mcp.md
│   ├── monitoring/
│   │   ├── _category_.json
│   │   ├── prometheus-mcp.md
│   │   ├── datadog-mcp.md
│   │   ├── grafana-mcp.md
│   │   └── splunk-mcp.md
│   ├── cicd/
│   │   ├── _category_.json
│   │   ├── jenkins-mcp.md
│   │   ├── argocd-mcp.md
│   │   ├── github-actions-mcp.md
│   │   └── gitlab-ci-mcp.md
│   └── communication/
│       ├── _category_.json
│       ├── slack-mcp.md
│       ├── pagerduty-mcp.md
│       └── opsgenie-mcp.md
│
├── configuration/
│   ├── _category_.json
│   ├── agent-configuration.md
│   ├── guardrails-setup.md
│   ├── permissions-rbac.md
│   ├── deployment-options.md
│   ├── environment-variables.md
│   └── custom-agents.md
│
├── api/
│   ├── _category_.json
│   ├── overview.md
│   ├── rest-api.md
│   ├── a2a-protocol.md
│   ├── webhooks.md
│   ├── authentication.md
│   ├── rate-limiting.md
│   └── custom-tools.md
│
├── administration/
│   ├── _category_.json
│   ├── user-management.md
│   ├── audit-logging.md
│   ├── compliance.md
│   ├── security.md
│   ├── monitoring-talkops.md
│   └── backup-recovery.md
│
├── troubleshooting/
│   ├── _category_.json
│   ├── common-issues.md
│   ├── debugging-agents.md
│   ├── performance-optimization.md
│   └── logs-telemetry.md
│
├── advanced/
│   ├── _category_.json
│   ├── custom-frameworks.md
│   └── production-deployment.md
│
└── reference/
    ├── _category_.json
    ├── glossary.md
    ├── architecture-diagram.md
    ├── security-whitepaper.md
    ├── release-notes.md
    └── faq.md

EXTENSIBILITY STRATEGY​

Adding New Agents (Future Growth)​

Pattern:

  1. Create folder: docs/agents/[new-agent]/
  2. Add files: overview.md, capabilities.md, configuration.md, etc.
  3. Update sidebars.js to add category
  4. Sidebar auto-updates

Example: Adding "Cost Optimization Agent"

{
  type: 'category',
  label: 'Cost Optimization Agent',
  collapsed: true,
  link: {
    type: 'doc',
    id: 'agents/cost-optimization/overview',
  },
  items: [
    'agents/cost-optimization/capabilities',
    'agents/cost-optimization/configuration',
    'agents/cost-optimization/examples',
    'agents/cost-optimization/troubleshooting',
  ],
},

Adding New MCP Servers (Future Growth)​

Pattern:

  1. Create file: docs/integrations/[category]/[provider]-mcp.md
  2. Add to appropriate category in sidebars.js
  3. New docs surface immediately

Example: Adding "DataDog Logs MCP"

// In integrations/monitoring/
{
  type: 'category',
  label: 'Monitoring & Observability',
  collapsed: true,
  items: [
    'integrations/monitoring/prometheus-mcp',
    'integrations/monitoring/datadog-mcp',
    'integrations/monitoring/datadog-logs-mcp', // NEW
    'integrations/monitoring/grafana-mcp',
  ],
},

DOCUSAURUS CONFIGURATION​

docusaurus.config.js Navbar​

navbar: {
  title: 'TalkOps',
  logo: {
    alt: 'TalkOps Logo',
    src: 'img/logo.svg',
  },
  items: [
    {
      type: 'docSidebar',
      sidebarId: 'docSidebar',
      position: 'left',
      label: 'Docs',
    },
    {
      href: 'https://github.com/yourusername/talkops',
      label: 'GitHub',
      position: 'right',
    },
  ],
},

SUMMARY​

This sidebar structure is:

  • ✅ Architecture-aware (mirrors your product)
  • ✅ Future-proof (scales from 5 MCPs → 50+)
  • ✅ Purpose-driven (organized by user jobs)
  • ✅ Cognitive load optimized
  • ✅ Ready to implement