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, getActiveProducts, getActiveVersions, generateRouteBasePath } 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));
    }
  });
});

// Filter to a single product when DOCS_PRODUCT is set, matching the filtering
// generateDocusaurusPlugins() applies — otherwise redirects reference routes
// from products that were never built in this run.
const targetProduct = process.env.DOCS_PRODUCT;

const latestVersionMap = getLatestVersionUrlMap();

// Match the product filtering generateDocusaurusPlugins() applies, so redirects
// never target a product whose pages weren't built for this DOCS_PRODUCT run.
const redirectProducts = getActiveProducts();

// Passed to the client via customFields: React components are bundled by
// rspack/webpack, which polyfill `process` with an empty env in that context,
// so process.env.DOCS_PRODUCT isn't readable from component code directly.
const activeProductIds = redirectProducts.map(product => product.id);
const activeVersionsByProduct = Object.fromEntries(
  redirectProducts.map(product => [product.id, getActiveVersions(product).map(v => v.version)])
);

// Docs base paths that currently serve pages without a version segment, used
// client-side to redirect stale /docs/<product>/<version>/<page> links to
// /docs/<product>/<page>. Derived from the route base path the plugin actually
// mounts rather than from the version name: a lone version named 'current' can
// still carry a customRoutePath (docs/identitymanager/current) and serve
// versioned URLs, so comparing against product.path is what makes the
// "unversioned" inference hold.
//
// Reads product.versions rather than getActiveVersions(product) on purpose:
// DOCS_PRODUCT_LATEST_ONLY narrows the active list to one version, which would
// make a genuinely multi-version product look collapsed and start rewriting its
// valid versioned URLs in local single-product builds.
const unversionedDocsBasePaths = redirectProducts
  .map(product => {
    if (product.versions.length !== 1) return null;
    const [version] = product.versions;
    const routeBasePath = version.customRoutePath || generateRouteBasePath(product.path, version.version);
    return routeBasePath === product.path ? `/${routeBasePath}` : null;
  })
  .filter(Boolean);

/** @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
  // Relaxed to 'warn' for single-product builds (DOCS_PRODUCT set): the navbar
  // always links to every product, but a filtered build only generates routes
  // for one of them, so cross-product navbar (site) links are expected to be
  // unresolved. Markdown links and anchors resolve within the target product's
  // own plugin instance regardless of filtering, so those stay strict to catch
  // real mistakes during single-product iteration.
  onBrokenLinks: targetProduct ? 'warn' : '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'],
  },
  customFields: {
    activeProductIds,
    activeVersionsByProduct,
    unversionedDocsBasePaths,
  },
  clientModules: ['./src/clientModules/scrollBehavior.js'],
  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: redirectProducts.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-changetracker',
        docsPluginId: 'changetracker',
        config: {
          'changetracker-hub': {
            specPath: 'static/openapi/changetracker-hub-8.2.yaml',
            outputDir: 'docs/changetracker/api/reference',
            sidebarOptions: {
              groupPathsBy: 'tag',
              categoryLinkSource: 'tag',
              sidebarCollapsed: true,
            },
            downloadUrl: '/openapi/changetracker-hub-8.2.yaml',
            version: 'current',
            label: 'Change Tracker Hub API',
            baseUrl: '/docs/changetracker/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: 'b38509adea6e7a1189bfb0d06ca37436', // Use the search-only API key, not the admin key
        indexName: 'Production Docs',

        // NOTE: overridden to false by the custom SearchBar (src/theme/SearchBar), which
        // injects product/version facet filters itself. Kept here for theme compatibility.
        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...',

        // 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;