sidebars.ts

import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';

/**
 * Sidebar Configuration
 *
 * This file defines the navigation structure for docs.convex.world.
 *
 * Key patterns used:
 *
 * 1. Category with link property:
 *    - Makes the category header clickable
 *    - Shows the index/overview page when clicked
 *    - Keeps the category expanded to show subitems
 *    - Maintains sidebar context (no drill-down)
 *
 * 2. Excluding index from items:
 *    - Since the link property points to the index, we don't list it again in items
 *    - This prevents duplication in the sidebar
 *
 * 3. Manual structure for Client SDKs:
 *    - Allows TypeScript and JavaScript to expand in-place
 *    - Keeps all SDK options visible in the hierarchy
 *    - Prevents losing context when navigating between SDKs
 *
 * 4. Consistent UX:
 *    - All categories use the same pattern
 *    - Clicking a category header shows its overview
 *    - Subitems remain visible and accessible
 */
const sidebars: SidebarsConfig = {
  // Overview sidebar: auto-generated from docs/overview/
  overviewSidebar: [{type: 'autogenerated', dirName: 'overview'}],

  // Tutorial sidebar: manually structured to maintain context and prevent duplication
  tutorialSidebar: [
    // Tutorial landing page
    'tutorial/index',

    // Quick start guide
    'tutorial/quickstart',

    // Networks guide
    'tutorial/networks',

    // Client SDKs - manually structured for in-place expansion
    // This allows TypeScript, JavaScript, Java, Python, Rust to all be visible
    // in the same hierarchy without drilling down and losing context
    {
      type: 'category',
      label: 'Client SDKs',
      link: {
        type: 'doc',
        id: 'tutorial/client-sdks/index',  // Shows SDK overview when clicked
      },
      items: [
        {
          type: 'category',
          label: 'TypeScript / JavaScript',
          link: {
            type: 'doc',
            id: 'tutorial/client-sdks/typescript/index',  // Shows TS overview when clicked
          },
          items: [
            // Note: index is NOT listed here - it's already the link target above
            'tutorial/client-sdks/typescript/quickstart',
            'tutorial/client-sdks/typescript/queries',
            'tutorial/client-sdks/typescript/transactions',
            'tutorial/client-sdks/typescript/accounts',
            'tutorial/client-sdks/typescript/assets',
            'tutorial/client-sdks/typescript/signers',
            // Same package (@convex-world/convex-ts), used from plain JavaScript
            'tutorial/client-sdks/javascript/index',
          ],
        },
        {
          type: 'category',
          label: 'Python',
          link: {
            type: 'doc',
            id: 'tutorial/client-sdks/python/index',  // Shows Python overview when clicked
          },
          items: [
            'tutorial/client-sdks/python/quickstart',
            'tutorial/client-sdks/python/queries',
            'tutorial/client-sdks/python/transactions',
            'tutorial/client-sdks/python/accounts',
            'tutorial/client-sdks/python/assets',
          ],
        },
        {
          type: 'category',
          label: 'Java',
          link: {
            type: 'doc',
            id: 'tutorial/client-sdks/java/index',  // Shows Java overview when clicked
          },
          items: [
            'tutorial/client-sdks/java/quickstart',
            'tutorial/client-sdks/java/clients',
            'tutorial/client-sdks/java/queries',
            'tutorial/client-sdks/java/transactions',
            'tutorial/client-sdks/java/accounts',
            'tutorial/client-sdks/java/assets',
          ],
        },
        // Future: Rust SDK will go here with same structure
      ],
    },

    // Convex Coins - simple category with overview and faucet guide
    {
      type: 'category',
      label: 'Convex Coins',
      link: {
        type: 'doc',
        id: 'tutorial/coins/index',  // Shows coins overview when clicked
      },
      items: [
        'tutorial/coins/faucet',  // Faucet guide
      ],
    },

    // Convex Lisp - category with multiple guide pages
    {
      type: 'category',
      label: 'Convex Lisp',
      link: {
        type: 'doc',
        id: 'tutorial/convex-lisp/index',  // Shows Lisp overview when clicked
      },
      items: [
        'tutorial/convex-lisp/lisp-cvm',
        'tutorial/convex-lisp/lisp-guide',
        'tutorial/convex-lisp/lisp-guide-advanced',
      ],
    },

    // Actor Development - smart contracts and autonomous actors
    {
      type: 'category',
      label: 'Actor Development',
      link: {
        type: 'doc',
        id: 'tutorial/actors/index',  // Shows actors overview when clicked
      },
      items: [
        'tutorial/actors/concepts',
        'tutorial/actors/building-an-actor',
        'tutorial/actors/deployment',
        'tutorial/actors/evolution',
        'tutorial/actors/best-practices',
      ],
    },

    // AI Agents - MCP integration, account management, agentic economics
    {
      type: 'category',
      label: 'AI Agents',
      link: {
        type: 'doc',
        id: 'tutorial/agents/index',
      },
      items: [
        'tutorial/agents/mcp',
        'tutorial/agents/account-management',
        'tutorial/agents/agentic-economics',
      ],
    },

    // Recipes - practical how-to guides
    {
      type: 'category',
      label: 'Recipes',
      link: {
        type: 'doc',
        id: 'tutorial/recipes/index',  // Shows recipes overview when clicked
      },
      items: [
        'tutorial/recipes/create-account/index',
        'tutorial/recipes/managing-coins/index',
        'tutorial/recipes/coin-distributor/index',
        'tutorial/recipes/account-control/index',
        'tutorial/recipes/issue-token/index',
      ],
    },

    // Peer Operations - running and operating Convex peers
    {
      type: 'category',
      label: 'Peer Operations',
      link: {
        type: 'doc',
        id: 'tutorial/peer-operations/index',
      },
      items: [
        'tutorial/peer-operations/staking',
        'tutorial/peer-operations/manual-deployment',
        'tutorial/peer-operations/docker-deployment',
        'tutorial/peer-operations/hosting',
        'tutorial/peer-operations/local-testnets',
        'tutorial/peer-operations/troubleshooting',
        'tutorial/peer-operations/security',
      ],
    },

    // Glossary - single page
    'tutorial/glossary',
  ],

  // Products sidebar: auto-generated from docs/products/
  productsSidebar: [{type: 'autogenerated', dirName: 'products'}],

  // CADs sidebar: auto-generated from docs/cad/ (Convex Architecture Documents)
  cadsSidebar: [{type: 'autogenerated', dirName: 'cad'}], 


  // But you can create a sidebar manually
  /*
  tutorialSidebar: [
    'intro',
    'hello',
    {
      type: 'category',
      label: 'Tutorial',
      items: ['tutorial-basics/create-a-document'],
    },
  ],
   */
};

export default sidebars;