team/docs/site/docusaurus.config.ts

import {themes as prismThemes} from 'prism-react-renderer';
import type {Config} from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';
// Active redirects (legacy Sphinx URLs → migrated MDX paths). Regenerated
// by `node docs-site/scripts/gen-active-redirects.mjs` after content
// changes; only entries whose target exists end up here.
import activeRedirects from './sidebars/active-redirects.json';

// Multi-instance docs setup with three top-level navigations:
//   /          → Documentation (admin / end-user)        sources: ../docs
//   /developers → Developers (contribute / integrate)    sources: ../develop
//   /api        → API Reference (OpenAPI-generated)      sources: ../api
// See PLAN.md §3.1 for the IA, §3.2 for design tokens.

// Docusaurus's Algolia schema rejects an empty `appId`/`apiKey`, so the
// block is only included when both are set. Without credentials the search
// bar is simply omitted (rather than rendered as an inert element), which
// keeps local and CI builds green.
const algoliaAppId = process.env.ALGOLIA_APP_ID;
const algoliaApiKey = process.env.ALGOLIA_SEARCH_API_KEY;
const algoliaThemeConfig =
  algoliaAppId && algoliaApiKey
    ? {
        algolia: {
          appId: algoliaAppId,
          apiKey: algoliaApiKey,
          indexName: 'mattermost-docs',
          contextualSearch: true,
          searchPagePath: 'search',
        },
      }
    : {};

const config: Config = {
  title: 'Mattermost Documentation',
  tagline: 'Mission in Motion',
  favicon: 'img/brand/icon-denim.svg',

  future: {
    v4: true,
  },

  url: 'https://docs.mattermost.com',
  baseUrl: process.env.BASE_URL ?? '/',
  trailingSlash: false,

  organizationName: 'mattermost',
  projectName: 'mattermost',

  // Broken-link / broken-image policy. During the Phase 4 (developer docs)
  // and Phase 5 (main docs) migrations, content references images and
  // anchors that haven't been migrated yet — `warn` keeps the build green
  // while the unconverted set shows up as warnings we can grep for.
  // Tighten to `throw` after each migration phase completes.
  onBrokenLinks: 'warn',

  markdown: {
    hooks: {
      onBrokenMarkdownLinks: 'warn',
      onBrokenMarkdownImages: 'warn',
    },
  },

  i18n: {
    defaultLocale: 'en',
    locales: ['en'],
  },

  // Google Fonts: Inter (body) + Archivo Black (headings, free Trade Gothic Heavy fallback).
  // Replace with Adobe Fonts kit once Trade Gothic Next licensing is confirmed
  // — see PLAN.md §12 open items.
  stylesheets: [
    {
      href: 'https://fonts.googleapis.com/css2?family=Archivo+Black&family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;600&display=swap',
      type: 'text/css',
    },
  ],
  headTags: [
    {tagName: 'link', attributes: {rel: 'preconnect', href: 'https://fonts.googleapis.com'}},
    {tagName: 'link', attributes: {rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: 'anonymous'}},
  ],

  // Use the classic preset for the default Documentation instance.
  // Developers and API are added as separate plugin instances below
  // to give each its own routeBasePath and sidebar.
  presets: [
    [
      'classic',
      {
        docs: {
          id: 'documentation',
          path: '../main',
          routeBasePath: '/',
          sidebarPath: './sidebars/documentation.ts',
          editUrl: 'https://github.com/mattermost/mattermost/tree/master/docs/main/',
        },
        blog: false,
        theme: {
          customCss: ['./src/css/tokens.css', './src/css/custom.css'],
        },
      } satisfies Preset.Options,
    ],
  ],

  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'developers',
        path: '../develop',
        routeBasePath: '/developers',
        sidebarPath: './sidebars/developers.ts',
        editUrl: 'https://github.com/mattermost/mattermost/tree/master/docs/develop/',
      },
    ],
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'api',
        path: '../api',
        routeBasePath: '/api',
        sidebarPath: './sidebars/api.ts',
        editUrl: 'https://github.com/mattermost/mattermost/tree/master/docs/api/',
        // Required for endpoint pages generated by docusaurus-plugin-openapi-docs.
        docItemComponent: '@theme/ApiItem',
      },
    ],
    [
      '@docusaurus/plugin-client-redirects',
      {
        // Legacy URL → migrated MDX path. Pre-filtered to entries whose
        // target exists, so the build never breaks on a missing target.
        redirects: activeRedirects.redirects,
      },
    ],
    // Generates API reference pages from the OpenAPI bundle produced by
    // build-openapi.mjs
    [
      'docusaurus-plugin-openapi-docs',
      {
        id: 'api-generator',
        docsPluginId: 'api',
        config: {
          mattermost: {
            specPath: 'openapi/mattermost-openapi-v4.yaml',
            outputDir: '../api/reference',
            sidebarOptions: {
              groupPathsBy: 'tag',
              categoryLinkSource: 'tag',
            },
          },
        },
      },
    ],
  ],

  // Theme for the API endpoint pages (parameter tables, request/response
  // schemas, code-sample picker). Layered on the classic preset theme.
  themes: ['docusaurus-theme-openapi-docs'],

  themeConfig: {
    image: 'img/brand/logo-horizontal-denim.svg',
    colorMode: {
      defaultMode: 'light',
      respectPrefersColorScheme: true,
    },
    navbar: {
      title: '',
      logo: {
        alt: 'Mattermost',
        // Navbar is denim in both light and dark mode, so white logo always.
        src: 'img/brand/logo-horizontal-white.svg',
        srcDark: 'img/brand/logo-horizontal-white.svg',
      },
      items: [
        {
          type: 'docSidebar',
          docsPluginId: 'documentation',
          sidebarId: 'documentation',
          position: 'left',
          label: 'Documentation',
        },
        {
          type: 'docSidebar',
          docsPluginId: 'developers',
          sidebarId: 'developers',
          position: 'left',
          label: 'Developers',
        },
        {
          type: 'docSidebar',
          docsPluginId: 'api',
          sidebarId: 'api',
          position: 'left',
          label: 'API',
        },
        {
          href: 'https://github.com/mattermost/mattermost',
          label: 'GitHub',
          position: 'right',
        },
      ],
    },
    footer: {
      style: 'dark',
      logo: {
        alt: 'Mattermost — Mission in Motion',
        src: 'img/brand/logo-horizontal-white.svg',
        width: 180,
      },
      links: [
        {
          title: 'Documentation',
          items: [
            {label: 'Product Overview', to: '/'},
            {label: 'Deployment Guide', to: '/'},
            {label: 'Administration Guide', to: '/'},
          ],
        },
        {
          title: 'Developers',
          items: [
            {label: 'Contribute', to: '/developers'},
            {label: 'Integrate & Extend', to: '/developers'},
            {label: 'API Reference', to: '/api'},
          ],
        },
        {
          title: 'Community',
          items: [
            {label: 'GitHub', href: 'https://github.com/mattermost/mattermost'},
            {label: 'Forum', href: 'https://forum.mattermost.com/'},
          ],
        },
      ],
      copyright: `Copyright © ${new Date().getFullYear()} Mattermost, Inc. All rights reserved.`,
    },
    ...algoliaThemeConfig,
    prism: {
      theme: prismThemes.github,
      darkTheme: prismThemes.dracula,
      additionalLanguages: ['bash', 'powershell', 'json', 'yaml', 'go', 'python'],
    },
    // Code-sample tabs shown on every endpoint page, in display order.
    // First entry is the default selected tab (curl).
    languageTabs: [
      {highlight: 'bash',       language: 'curl',       logoClass: 'curl'},
      {highlight: 'powershell', language: 'powershell', logoClass: 'powershell'},
      {highlight: 'python',     language: 'python',     logoClass: 'python'},
      {highlight: 'javascript', language: 'nodejs',     logoClass: 'nodejs',     label: 'Node'},
      {highlight: 'go',         language: 'go',         logoClass: 'go'},
    ],
  } satisfies Preset.ThemeConfig,
};

export default config;