docusaurus.config.ts

import fs from 'node:fs';
import path from 'node:path';

import { logger } from '@docusaurus/logger';
import type { Config } from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';
import npm2yarn from '@docusaurus/remark-plugin-npm2yarn';
import * as dotenv from 'dotenv';
import { themes as prismThemes } from 'prism-react-renderer';
import remarkGithubAdmonitionsToDirectives, {
  DEFAULT_MAPPING,
} from 'remark-github-admonitions-to-directives';

import apiLabels from './src/transformers/api-labels.ts';
import apiOptionsClass from './src/transformers/api-options-class.ts';
import apiStructurePreviews from './src/transformers/api-structure-previews.ts';
import jsCodeBlocks from './src/transformers/js-code-blocks.ts';
import fiddleEmbedder from './src/transformers/fiddle-embedder.ts';
import githubContentsLinks from './src/transformers/github-content-links.ts';
import apiHistory from './src/transformers/api-history.ts';

// Picks up a local GITHUB_TOKEN so API history tables resolve versions in local
// dev. Existing environment variables win, which keeps CI behavior unchanged.
dotenv.config();

let docsSHA = undefined;

try {
  docsSHA = fs
    .readFileSync(path.resolve(__dirname, './docs/latest/.sha'), 'utf-8')
    .trim();
} catch {
  logger.warn('No .sha file found in docs/latest directory');
}

const config: Config = {
  title: 'Electron',
  tagline: 'Build cross-platform desktop apps with JavaScript, HTML, and CSS',
  url: 'https://electronjs.org',
  baseUrl: '/',
  onBrokenLinks: 'warn',
  favicon: 'assets/img/favicon.ico',
  organizationName: 'electron',
  projectName: 'electron',
  headTags: docsSHA
    ? [
        {
          tagName: 'meta',
          attributes: {
            name: 'docs-sha',
            content: docsSHA,
          },
        },
      ]
    : [],
  markdown: {
    mermaid: true,
  },
  themes: ['@docusaurus/theme-mermaid'],
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'de', 'es', 'fr', 'ja', 'pt', 'ru', 'zh'],
    path: 'i18n',
    // Due to a refactor in Docusaurus 3.9, the inferred localeDropdown baseURL paths
    // get messed up because we build the `en` locale separately from the translated ones.
    // This part of the config defines those manually.
    localeConfigs: {
      de: {
        baseUrl: '/de/',
      },
      es: {
        baseUrl: '/es/',
      },
      fr: {
        baseUrl: '/fr/',
      },
      ja: {
        baseUrl: '/ja/',
      },
      pt: {
        baseUrl: '/pt/',
      },
      ru: {
        baseUrl: '/ru/',
      },
      zh: {
        baseUrl: '/zh/',
      },
    },
  },
  themeConfig: {
    colorMode: {
      //Default to light or dark depending on system theme.
      respectPrefersColorScheme: true,
    },
    prism: {
      theme: prismThemes.github,
      darkTheme: prismThemes.dracula,
      additionalLanguages: ['diff', 'json', 'json5'],
    },
    tableOfContents: {
      minHeadingLevel: 2,
      maxHeadingLevel: 4,
    },
    navbar: {
      title: 'Electron',
      style: 'dark',
      logo: {
        alt: 'Electron homepage',
        src: 'assets/img/logo.svg',
      },
      items: [
        {
          label: 'Docs',
          type: 'doc',
          docId: 'latest/tutorial/introduction',
          position: 'left',
        },
        {
          label: 'API',
          type: 'doc',
          docId: 'latest/api/app',
          position: 'left',
        },
        { to: 'blog', label: 'Blog', position: 'left' },
        {
          type: 'dropdown',
          label: 'Tools',
          position: 'left',
          items: [
            { to: 'https://electronforge.io', label: 'Electron Forge' },
            { to: 'fiddle', label: 'Electron Fiddle' },
          ],
        },
        {
          type: 'dropdown',
          label: 'Community',
          position: 'left',
          items: [
            { to: 'governance', label: 'Governance' },
            { to: 'apps', label: 'Showcase' },
            { to: 'community', label: 'Resources' },
          ],
        },
        {
          href: 'https://releases.electronjs.org',
          label: 'Releases',
          position: 'right',
        },
        {
          type: 'localeDropdown',
          position: 'right',
        },
        {
          href: 'https://github.com/electron/electron',
          position: 'right',
          className: 'header-github-link',
          'aria-label': 'GitHub repository',
        },
      ],
    },
    footer: {
      logo: {
        alt: 'OpenJS Foundation Logo',
        src: 'assets/img/openjsf_logo.svg',
        srcDark: 'assets/img/openjsf_logo-dark.svg',
        href: 'https://openjsf.org/',
      },
      links: [
        {
          title: 'Docs',
          items: [
            {
              label: 'Getting Started',
              to: '/docs/latest/',
            },
            {
              label: 'API Reference',
              to: '/docs/latest/api/app',
            },
          ],
        },
        {
          title: 'Checklists',
          items: [
            {
              label: 'Performance',
              to: '/docs/latest/tutorial/performance',
            },
            {
              label: 'Security',
              to: '/docs/latest/tutorial/security',
            },
          ],
        },
        {
          title: 'Tools',
          items: [
            {
              label: 'Electron Forge',
              to: 'https://electronforge.io',
            },
            {
              label: 'Electron Fiddle',
              to: '/fiddle',
            },
          ],
        },
        {
          title: 'Community',
          items: [
            { label: 'Governance', to: '/governance' },
            { label: 'Resources', to: '/community' },
            {
              label: 'Bluesky',
              href: 'https://bsky.app/profile/electronjs.org',
            },
            {
              label: 'X',
              href: 'https://x.com/electronjs',
            },
            {
              html: '<a href="https://social.lfx.dev/@electronjs" target="_blank" rel="me" class="footer__link-item">Mastodon<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" style="margin-left: 0.3rem;"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a>',
            },
            {
              label: 'Stack Overflow',
              href: 'https://stackoverflow.com/questions/tagged/electron',
            },
          ],
        },
        {
          title: 'More',
          items: [
            {
              label: 'GitHub',
              href: 'https://github.com/electron/electron',
            },
            {
              label: 'Open Collective',
              href: 'https://opencollective.com/electron',
            },
            {
              label: 'Infrastructure Dashboard',
              href: 'https://p.datadoghq.com/sb/c44e1df0-85d7-11ee-94c9-da7ad0900002-c245f7ef47d0d0c32abecdc0938c2a85',
            },
          ],
        },
      ],
      copyright: `
        <p>Copyright <a href="https://openjsf.org">OpenJS Foundation</a> and Electron contributors. All rights reserved. 
          The <a href="https://openjsf.org">OpenJS Foundation</a> has registered trademarks and uses trademarks.  
          For a list of trademarks of the <a href="https://openjsf.org">OpenJS Foundation</a>, please see our 
          <a href="https://trademark-policy.openjsf.org">Trademark Policy</a> and <a href="https://trademark-list.openjsf.org">Trademark List</a>.  
          Trademarks and logos not indicated on the <a href="https://trademark-list.openjsf.org">list of OpenJS Foundation trademarks</a> 
          are trademarks&trade; or registered&reg; trademarks of their respective holders. Use of them does not imply any affiliation with 
          or endorsement by them.</p>
        <p><a href="https://openjsf.org">The OpenJS Foundation</a> | <a href="https://terms-of-use.openjsf.org">Terms of Use</a> | 
          <a href="https://privacy-policy.openjsf.org">Privacy Policy</a> | <a href="https://bylaws.openjsf.org">Bylaws</a> | 
          <a href="https://code-of-conduct.openjsf.org">Code of Conduct</a> | <a href="https://trademark-policy.openjsf.org">Trademark Policy</a>
          | <a href="https://trademark-list.openjsf.org">Trademark List</a> | <a href="https://www.linuxfoundation.org/cookies">Cookie Policy</a></p>`,
    },
    algolia: {
      appId: 'MG3SRMK3K0',
      apiKey: 'fdc2cf6080e499639d7e6b0278851ed4',
      indexName: 'electronjs',
      contextualSearch: true,
    },
  } satisfies Preset.ThemeConfig,
  plugins: [
    'docusaurus-plugin-sass',
    path.resolve(__dirname, './src/plugins/apps/index.ts'),
    path.resolve(__dirname, './src/plugins/releases/index.ts'),
    path.resolve(__dirname, './src/plugins/fiddle/index.ts'),
    path.resolve(__dirname, './src/plugins/governance/index.ts'),
    path.resolve(__dirname, './src/plugins/markdown-output/index.ts'),
    path.resolve(__dirname, './src/plugins/og-image/index.ts'),
  ],
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          path: 'docs',
          beforeDefaultRemarkPlugins: [
            [
              remarkGithubAdmonitionsToDirectives,
              {
                mapping: DEFAULT_MAPPING,
              },
            ],
          ],
          sidebarPath: require.resolve('./sidebars.js'),
          // The default generator sorts `autogenerated` items by file path,
          // which orders `certificate-principal.md` before `certificate.md`
          // ('-' sorts before '.'). Sort by doc id instead so that a doc
          // comes before the docs whose names extend it.
          sidebarItemsGenerator: async ({
            defaultSidebarItemsGenerator,
            ...args
          }) => {
            const items = await defaultSidebarItemsGenerator(args);
            const sortKey = (item: (typeof items)[number]) => {
              if (item.type === 'doc') return item.id;
              return 'label' in item ? (item.label ?? '') : '';
            };
            return [...items].sort((a, b) =>
              sortKey(a).localeCompare(sortKey(b), 'en'),
            );
          },
          routeBasePath: '/docs/',
          editUrl: ({ docPath }) => {
            const fixedPath = docPath.replace('latest/', '');
            return `https://github.com/electron/electron/edit/main/docs/${fixedPath}`;
          },
          remarkPlugins: [
            apiLabels,
            apiOptionsClass,
            apiStructurePreviews,
            jsCodeBlocks,
            fiddleEmbedder,
            githubContentsLinks,
            apiHistory,
            [npm2yarn, { sync: true, converters: ['yarn'] }],
          ],
        },
        blog: {
          // See `node_modules/@docusaurus/plugin-content-blog/src/pluginOptionSchema.ts` for full undocumented options
          path: 'blog',
          beforeDefaultRemarkPlugins: [remarkGithubAdmonitionsToDirectives],
          blogSidebarCount: 'ALL',
          blogSidebarTitle: 'Latest posts',
          blogTitle: `Electron's blog`,
          blogDescription: `Keep up to date with what's going on with the Electron project`,
          onInlineAuthors: 'ignore',
          onUntruncatedBlogPosts: 'ignore',
        },
        theme: {
          customCss: [require.resolve('./src/css/custom.scss')],
        },
        gtag: {
          trackingID: 'UA-160365006-1',
          anonymizeIP: true,
        },
      } satisfies Preset.Options,
    ],
  ],
  future: {
    faster: {
      rspackBundler: true,
      rspackPersistentCache: false,
      swcHtmlMinimizer: true,
      ssgWorkerThreads: true,
      swcJsLoader: true,
      swcJsMinimizer: true,
      lightningCssMinimizer: true,
      mdxCrossCompilerCache: true,
    },
    v4: {
      removeLegacyPostBuildHeadAttribute: true,
      // FIXME: enabling this change breaks compilation
      useCssCascadeLayers: false,
    },
  },
};

export default config;