sidebars.ts

import {existsSync} from 'node:fs';
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';

const sidebars: SidebarsConfig = {
  tutorialSidebar: [
    {
      type: 'category',
      label: 'Getting Started',
      collapsed: false,
      items: ['intro', 'choosing-a-variant', 'architecture', 'installation', 'verifying-downloads', 'installer', 'system-requirements', 'desktop-comparison', 'plasma-shortcuts', 'layering', 'smart-card-login', 'bootc-rollback', 'bootc-resources', 'faq', 'ublue-ecosystem'],
    },
    {
      type: 'category',
      label: 'Guides',
      collapsed: false,
      items: [
        'accessibility-features-guide',
        {type: 'category', label: 'Development', collapsed: true, items: ['guides/AI-DEVELOPMENT-QUICKSTART', 'guides/GAMEDEV-QUICKSTART', 'guides/KERNEL-DEVELOPER-QUICKSTART', 'guides/linux-audio-creative-bootc', 'guides/linux-gaming-bootc']},
        {type: 'category', label: 'Deployment', collapsed: true, items: ['guides/ENTERPRISE-VDI-DEPLOYMENT', 'guides/EDU-LAB-DEPLOYMENT', 'guides/DIGITAL-SIGNAGE-KIOSK-DEPLOYMENT', 'guides/INDUSTRIAL-IOT-EDGE-DEPLOYMENT', 'guides/PUBLIC-LIBRARY-DEPLOYMENT', 'guides/RETAIL-POS-DEPLOYMENT']},
        {type: 'category', label: 'Administration', collapsed: true, items: ['guides/SECURITY-WORKSTATION-QUICKSTART', 'guides/EPHEMERAL-SESSION-RESET']},
      ],
    },
    {
      type: 'category',
      label: 'Variants',
      collapsed: false,
      // Showcase: the rich, visual landing pages (custom React pages), with the
      // detailed per-variant reference docs nested beneath.
      items: [
        {type: 'link', label: 'Albacore — AlmaLinux 10', href: '/albacore'},
        {type: 'link', label: 'Yellowfin — AlmaLinux Kitten', href: '/yellowfin'},
        {type: 'link', label: 'Skipjack — CentOS Stream 10', href: '/skipjack'},
        {type: 'link', label: 'Bonito — Fedora 44', href: '/bonito'},
        {type: 'link', label: 'All variants (Ubuntu, Arch, Debian, …)', href: '/variants'},
        {type: 'category', label: 'Reference docs', collapsed: true, items: ['albacore', 'yellowfin', 'bonito', 'skipjack', 'grouper', 'gurnard/index', 'gurnard/pantheon-shortcuts', 'marlin', 'gurnard-pantheon', 'niri-quickstart', 'cosmic-quickstart']},
      ],
    },
    {
      type: 'category',
      label: 'TunaOS',
      link: {type: 'doc', id: 'tunaos/index'},
      items: [
        'tunaos/ROADMAP',
        'tunaos/CONTRIBUTING',
        'tunaos/SECURITY',
        'tunaos/hacktoberfest-2026',
        {
          type: 'category',
          label: 'Developer Guide',
          collapsible: true,
          collapsed: true,
          items: ['secure-boot', 'tunaos/introduction', 'tunaos/evaluating-in-a-vm', 'tunaos/building', 'tunaos/ai-ml-development', 'tunaos/bootc-usage', 'tunaos/cosmic-desktop', 'tunaos/homebrew', 'tunaos/platform-engineering', 'tunaos/live-iso-generation', 'tunaos/installer-walkthrough/index', 'tunaos/ci-cd', 'tunaos/troubleshooting'],
        },
      ],
    },
    {
      type: 'category',
      label: 'BuildStream Desktops',
      collapsed: false,
      items: [
        {type: 'category', label: 'Tromsø', link: {type: 'doc', id: 'tromso/index'}, items: ['tromso/SPEC', 'tromso/ROADMAP', 'tromso/SECURITY', 'tromso/CONTRIBUTING', 'tromso/ci-and-iso-pipeline']},
        {type: 'category', label: 'XFCE Linux', className: 'sidebar-alpha', link: {type: 'doc', id: 'xfce-linux/index'}, items: ['xfce-linux/docs-README', 'xfce-linux/PROJECT_STATUS', 'xfce-linux/CONTRIBUTING', 'xfce-linux/ROADMAP', 'xfce-linux/SECURITY', 'xfce-linux/ci-and-iso-pipeline']},
      ],
    },
    {
      type: 'category',
      label: 'Tools',
      collapsed: false,
      items: [
        {type: 'category', label: 'wootc', link: {type: 'doc', id: 'wootc/index'}, items: ['wootc/getting-started', 'wootc/user-guide', 'wootc/philosophy', 'wootc/status', 'wootc/ROADMAP', 'wootc/CONTRIBUTING']},
        {type: 'category', label: 'Tacklebox', link: {type: 'doc', id: 'tacklebox/index'}, items: ['tacklebox/USER-GUIDE', 'tacklebox/ARCHITECTURE', 'tacklebox/github-iso-setup', 'tacklebox/TODO', 'tacklebox/ROADMAP', 'tacklebox/SECURITY', 'tacklebox/CONTRIBUTING', 'tacklebox/opfs-streaming-handoff']},
        {type: 'category', label: 'ISO Builder', link: {type: 'doc', id: 'iso-builder/index'}, items: [{type: 'category', label: 'Native App', link: {type: 'doc', id: 'iso-builder/native/index'}, items: ['iso-builder/native/user-guide']}]},
        {type: 'category', label: 'remora', link: {type: 'doc', id: 'remora/index'}, items: []},
        {
          type: 'category',
          label: 'Corral',
          link: {type: 'doc', id: 'corral/index'},
          items: ['corral/user-guide', 'corral/vdi', 'corral/host-power', 'corral/ROADMAP', 'corral/SPEC', 'corral/architecture', 'corral/api', 'corral/backend-support', 'corral/backend-parity', 'corral/ci-boot-gate', 'corral/first-party-plugins', 'corral/kubevirt-proxmox-setup', 'corral/plugin-marketplace', 'corral/proxmox-api', 'corral/testing'],
        },
        {
          type: 'category',
          label: 'bluefin-cli',
          link: {type: 'doc', id: 'bluefin-cli/index'},
          items: ['bluefin-cli/ai', 'bluefin-cli/cncf', 'bluefin-cli/gnome', 'bluefin-cli/menus', 'bluefin-cli/tools', 'bluefin-cli/vanilla-vs-extra', 'bluefin-cli/ROADMAP', 'bluefin-cli/CONTRIBUTING'],
        },
        {
          type: 'category',
          label: 'bootc-migrate',
          link: {type: 'doc', id: 'bootc-migrate/index'},
          items: ['bootc-migrate/architecture', 'bootc-migrate/filesystem-support', 'bootc-migrate/luks-testing', 'bootc-migrate/testing', 'bootc-migrate/references', 'bootc-migrate/ROADMAP', 'bootc-migrate/CONTRIBUTING', 'bootc-migrate/cfs-cli-generations'],
        },
        {type: 'category', label: 'Flatpak', link: {type: 'doc', id: 'flatpak/index'}, items: ['flatpak/guide', 'flatpak-remote-operations']},
        {type: 'category', label: 'tunaos-packages', link: {type: 'doc', id: 'tunaos-packages/index'}, items: ['tunaos-packages/ARCHITECTURE', 'tunaos-packages/PACKAGE_FACTORY', 'tunaos-packages/PATCH_POLICY', 'tunaos-packages/ROADMAP', 'tunaos-packages/SECURITY', 'tunaos-packages/TIDEFORGE-READINESS', 'tunaos-packages/UPSTREAM_PARITY', 'tunaos-packages/XFWL4-PORTING', 'tunaos-packages/hummingbird-desktop-gap', 'tunaos-packages/CONTRIBUTING']},
        {type: 'category', label: 'Ubuntu', link: {type: 'doc', id: 'ubuntu/index'}, items: ['ubuntu/CONTRIBUTING', 'ubuntu/SECURITY']},
        {type: 'category', label: 'bootc-installer-tui', link: {type: 'doc', id: 'bootc-installer-tui/index'}, items: ['bootc-installer-tui/CONTRIBUTING']},
        {type: 'category', label: 'chunkah', link: {type: 'doc', id: 'chunkah/index'}, items: ['chunkah/CONTRIBUTING']},
      ],
    },
    {
      type: 'category',
      label: 'Images & ISOs',
      collapsed: false,
      items: [
        {type: 'doc', id: 'tromso-iso/index', label: 'Tromsø ISO'},
        {type: 'doc', id: 'dakota-iso/index', label: 'Dakota ISO'},
        {type: 'doc', id: 'xfce-linux-iso/index', label: 'XFCE Linux ISO'},
        {type: 'doc', id: 'ubuntu-26-04-iso/index', label: 'Ubuntu 26.04 ISO'},
        {type: 'doc', id: 'bonito-x13s/index', label: 'Bonito X13s'},
        {type: 'doc', id: 'dakota-x13s/index', label: 'Dakota X13s'},
      ],
    },
    {
      type: 'category',
      label: 'Apps',
      collapsed: false,
      items: [
        {type: 'category', label: 'Tavern', link: {type: 'doc', id: 'tavern/index'}, items: ['tavern/ROADMAP', 'tavern/CONTRIBUTING']},
        {type: 'category', label: 'Compass', link: {type: 'doc', id: 'compass/index'}, items: ['compass/getting-started', 'compass/CONTRIBUTING']},
        {
          type: 'category',
          label: 'Office Suite',
          link: {type: 'doc', id: 'gtk-office-suite/index'},
          items: ['gtk-office-suite/letters', 'gtk-office-suite/tables', 'gtk-office-suite/decks'],
        },
        {type: 'category', label: 'Mariner', link: {type: 'doc', id: 'mariner/index'}, items: []},
        {type: 'category', label: 'Mandelbrot', link: {type: 'doc', id: 'mandelbrot/index'}, items: ['mandelbrot/features']},
        {type: 'category', label: 'Blueshell', link: {type: 'doc', id: 'blueshell/index'}, items: []},
        {type: 'category', label: 'Ghostty', className: 'sidebar-external', link: {type: 'doc', id: 'ghostty/index'}, items: []},
      ],
    },
    {type: 'html', value: '<div class="sidebar-section-label">Community</div>', defaultStyle: true},
    'community',
    'sync-org-docs-guide',
    {type: 'category', label: 'Dakota (Bluefin)', className: 'sidebar-external', link: {type: 'doc', id: 'dakota/index'}, items: ['dakota/migration']},
  ],
};

// Many entries point into docs/<project>/ trees that sync-org-docs rewrites
// from their source repos every day. A page renamed or removed upstream used
// to fail the whole build (checkSidebarsDocIds), which blocked every synced
// update for a week until someone edited this file. An entry whose page is
// gone is now dropped with a warning instead; the build log still names it.
type Item = Extract<SidebarsConfig[string], unknown[]>[number];

function docExists(id: string): boolean {
  return ['.md', '.mdx'].some(ext => existsSync(`docs/${id}${ext}`));
}

function present(items: Item[]): Item[] {
  return items.flatMap<Item>(item => {
    if (typeof item === 'string') {
      if (docExists(item)) return [item];
      console.warn(`[sidebars] dropping '${item}': docs/${item}.md is gone`);
      return [];
    }
    if (item && typeof item === 'object' && 'type' in item) {
      if (item.type === 'doc' && !docExists(item.id)) {
        console.warn(`[sidebars] dropping '${item.id}': docs/${item.id}.md is gone`);
        return [];
      }
      if (item.type === 'category') {
        const category = {...item, items: present(item.items as Item[])};
        if (category.link && category.link.type === 'doc' && !docExists(category.link.id)) {
          console.warn(`[sidebars] '${category.label}' loses its link: docs/${category.link.id}.md is gone`);
          delete category.link;
        }
        if (!category.link && category.items.length === 0) {
          console.warn(`[sidebars] dropping '${category.label}': none of its pages is left`);
          return [];
        }
        return [category];
      }
    }
    return [item];
  });
}

for (const name of Object.keys(sidebars)) {
  sidebars[name] = present(sidebars[name] as Item[]);
}

export default sidebars;