docusaurus.config.js

// @ts-check
// `@type` JSDoc annotations allow editor autocompletion and type checking
// (when paired with `@ts-check`).
// There are various equivalent ways to declare your Docusaurus config.
// See: https://docusaurus.io/docs/api/docusaurus-config

import { readFileSync, existsSync } from 'fs';
import { resolve } from 'path';
import { themes as prismThemes } from 'prism-react-renderer';
import { generateDocusaurusPlugins, generateNavbarDropdowns, PRODUCTS, versionToUrl, getDefaultVersion, getLatestVersionUrlMap } from './src/config/products.js';

// Strip TypeScript syntax from a generated sidebar.ts and return its apisidebar array.
// Returns [] if the file doesn't exist yet (before gen-api-docs has run).
// Runs in Node.js only (docusaurus.config.js is never bundled for the browser).
function loadApiSidebarItems(sidebarTsPath) {
  if (!existsSync(sidebarTsPath)) return [];
  let content = readFileSync(sidebarTsPath, 'utf8');
  content = content
    .replace(/^import type[^\n]*\n/m, '')
    .replace(/const sidebar:\s+\w+\s*=\s*\{/, 'const sidebar = {')
    .replace(/export default sidebar\.apisidebar;/, 'return sidebar.apisidebar;');
  return (new Function(content))();
}

const apiSidebars = {};
PRODUCTS.forEach(product => {
  product.versions.forEach(version => {
    if (version.apiSidebarPath) {
      apiSidebars[version.apiSidebarPath] = loadApiSidebarItems(resolve(version.apiSidebarPath));
    }
  });
});

const latestVersionMap = getLatestVersionUrlMap();

/** @type {import('@docusaurus/types').Config} */
const config = {
  title: 'Netwrix Product Documentation',
  tagline: 'Documentation for Netwrix Products',
  favicon: 'branding/favicon.ico',

  // Set the production url of your site here
  // Use environment variable for dynamic URL configuration
  projectName: 'docs',
  url: process.env.APP_EXTERNAL_URL || 'http://localhost:4500',
  // Set the /<baseUrl>/ pathname under which your site is served
  baseUrl: '/',

  // throw on anything that is not configured correctly
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'throw',
  onBrokenAnchors: 'throw',

  // Set Mermaid
  markdown: {
    mermaid: true,
    // Strip trailing periods from title/sidebar_label in generated API operation pages.
    // The OpenAPI summaries often end with a period; Docusaurus uses title as the
    // prev/next pagination label, so this cleans up navigation text site-wide.
    parseFrontMatter: async (params) => {
      const result = await params.defaultParseFrontMatter(params);
      if (params.filePath.includes('/api/reference/')) {
        if (result.frontMatter.title) {
          result.frontMatter.title = result.frontMatter.title.replace(/\.$/, '');
        }
        if (result.frontMatter.sidebar_label) {
          result.frontMatter.sidebar_label = result.frontMatter.sidebar_label.replace(/\.$/, '');
        }
      }
      return result;
    },
  },
  themes: ['@docusaurus/theme-mermaid', 'docusaurus-theme-openapi-docs'],

  // Performance optimizations with Docusaurus Faster
  future: {
    faster: {
      swcJsLoader: true,
      swcJsMinimizer: true,
      swcHtmlMinimizer: true,
      lightningCssMinimizer: true,
      rspackBundler: true,
      rspackPersistentCache: true,
      mdxCrossCompilerCache: true,
      ssgWorkerThreads: false,
    },
    v4: {
      removeLegacyPostBuildHeadAttribute: true,
    },
  },

  // Even if you don't use internationalization, you can use this field to set
  // useful metadata like html lang. For example, if your site is Chinese, you
  // may want to replace "en" with "zh-Hans".
  i18n: {
    defaultLocale: 'en',
    locales: ['en'],
  },
  presets: [
    [
      'classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: false,
        blog: false,
        theme: {
          customCss: './src/css/custom.css',
        },
      }),
    ],
  ],

  plugins: [
      // Disable scope hoisting to prevent O(n²) hang on large module graphs
      function customRspackPlugin() {
        return {
          name: 'custom-rspack-config',
          configureWebpack(_config, isServer) {
            if (!isServer) {
              return { optimization: { concatenateModules: false } };
            }
            return {};
          },
        };
      },

      // Google Analytics
      [
        '@docusaurus/plugin-google-gtag',
      {
        trackingID: 'G-FZPWSDMTEX',
        anonymizeIP: true,
      },
    ],
    // Client-side redirects - redirect base product URLs to latest version
    [
      '@docusaurus/plugin-client-redirects',
      {
        redirects: PRODUCTS.filter(product => {
          // Only create redirects for products with multiple versions (not just 'current')
          return !(product.versions.length === 1 && product.versions[0].version === 'current');
        }).map(product => {
          const latestVersion = getDefaultVersion(product);
          const latestVersionUrl = versionToUrl(latestVersion.version);

          // Use explicit customRoutePath if specified (e.g., for multi-versioned products with 'current')
          // Otherwise use standard path generation
          const targetPath = latestVersion.customRoutePath
            ? latestVersion.customRoutePath
            : `${product.path}/${latestVersionUrl}`;

          return {
            from: `/${product.path}`,
            to: `/${targetPath}`,
          };
        }),
        createRedirects(existingPath) {
          for (const [productId, latestUrlVersion] of Object.entries(latestVersionMap)) {
            const versionedPrefix = `/docs/${productId}/${latestUrlVersion}/`;
            if (existingPath.startsWith(versionedPrefix)) {
              const rest = existingPath.slice(versionedPrefix.length).replace(/\/$/, '');
              if (!rest) return undefined;
              return [`/docs/${productId}/${rest}`];
            }
          }
          return undefined;
        },
      },
    ],
    // Generate all product documentation plugins from centralized configuration
    ...generateDocusaurusPlugins({ apiSidebars }).map(([pluginName, config]) => [
      pluginName,
      {
        ...config,
        sidebarPath: config.sidebarPath && typeof config.sidebarPath === 'string'
          ? require.resolve(config.sidebarPath)
          : config.sidebarPath,
      },
    ]),
    [
      'docusaurus-plugin-openapi-docs',
      {
        id: 'openapi',
        docsPluginId: 'changetracker8_1',
        config: {
          'changetracker-hub': {
            specPath: 'static/openapi/changetracker-hub-8.1.yaml',
            outputDir: 'docs/changetracker/8.1/api/reference',
            sidebarOptions: {
              groupPathsBy: 'tag',
              categoryLinkSource: 'tag',
              sidebarCollapsed: true,
            },
            downloadUrl: '/openapi/changetracker-hub-8.1.yaml',
            version: '8.1',
            label: 'ChangeTracker Hub 8.1 API',
            baseUrl: '/docs/changetracker/8_1/api/reference/',
          },
        },
      },
    ],
    [
      'docusaurus-plugin-openapi-docs',
      {
        id: 'openapi-8-2',
        docsPluginId: 'changetracker8_2',
        config: {
          'changetracker-hub-8-2': {
            specPath: 'static/openapi/changetracker-hub-8.2.yaml',
            outputDir: 'docs/changetracker/8.2/api/reference',
            sidebarOptions: {
              groupPathsBy: 'tag',
              categoryLinkSource: 'tag',
              sidebarCollapsed: true,
            },
            downloadUrl: '/openapi/changetracker-hub-8.2.yaml',
            version: '8.2',
            label: 'ChangeTracker Hub 8.2 API',
            baseUrl: '/docs/changetracker/8_2/api/reference/',
          },
        },
      },
    ],
  ],

  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      // MermaidJS Config
      mermaid: {
        theme: {
          light: 'neutral',
          dark: 'dark',
        },
        options: {
          look: 'handDrawn',
          handDrawnSeed: 1,
        },
      },
      // Replace with your project's social card
      image: 'img/Logo_RGB.svg',
      docs: {
        sidebar: {
          hideable: true,
          autoCollapseCategories: true,
        },
      },
      algolia: {
        // Your Algolia credentials
        appId: 'KPMSCF6G6J',
        apiKey: '1b20f30f13a874cd46f9d5c30b01d99c', // Use the search-only API key, not the admin key
        indexName: 'Production Docs',

        // Enable contextual search (already great that you have product/version meta tags!)
        contextualSearch: true,

        // Search parameters for better results
        searchParameters: {
          // Facet filters can be combined with contextual search
          // These will be merged with the automatic facets from contextual search
          facetFilters: [
            // Add any default filters here if needed
            // e.g., 'type:content' to exclude headers-only results
          ],

          // Attributes to snippet in search results
          attributesToSnippet: ['content:20'],

          // Highlight search terms in results
          highlightPreTag: '<mark>',
          highlightPostTag: '</mark>',

          // Number of results per page
          hitsPerPage: 20,

          // Add these for better relevance
          distinct: true,
          clickAnalytics: true,
          analytics: true,
        },

        // Enable search insights for better analytics
        insights: true,

        // Path for the search page (enables full-page search experience)
        searchPagePath: 'search',

        // Placeholder text for the search box
        placeholder: 'Search the Netwrix docs...',

        // Transform items before displaying (optional)
        transformItems: (items) => {
          return items.map((item) => {
            // Add product badges or modify display as needed
            return {
              ...item,
              // Example: Add custom badges based on product
              _highlightResult: {
                ...item._highlightResult,
                // Customize highlighted results if needed
              },
            };
          });
        },

        // Replace paths if you're using different deployments
        // replaceSearchResultPathname: {
        //   from: '/docs/',
        //   to: '/',
        // },
      },
      navbar: {
        logo: {
          alt: 'Netwrix Logo',
          src: 'branding/Netwrix_Logo_Dark.svg',
          srcDark: 'branding/logo-light.svg',
          href: '/',
        },
        items: [
          // Generate category dropdowns from centralized product configuration
          ...generateNavbarDropdowns(),
          {
            href: 'https://community.netwrix.com',
            label: 'Community',
            position: 'right',
          },
          {
            href: 'https://www.netwrix.com/support.html',
            label: 'Support',
            position: 'right',
          },
          {
            href: 'http://github.com/netwrix',
            label: 'GitHub',
            position: 'right',
          },
        ],
      },
      prism: {
        theme: prismThemes.github,
        darkTheme: prismThemes.dracula,
        additionalLanguages: ['powershell', 'bash'],
      },
    }),
  // Add preconnect for better search performance
  headTags: [
    {
      tagName: 'link',
      attributes: {
        rel: 'preconnect',
        href: 'https://KPMSCF6G6J-dsn.algolia.net',
        crossorigin: 'anonymous',
      },
    },
  ],
  stylesheets: ['https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap'],
};

export default config;