astro.config.mjs

// @ts-check

import { fileURLToPath } from "node:url";
import node from "@astrojs/node";
import partytown from "@astrojs/partytown";
import react from "@astrojs/react";
import sitemap from "@astrojs/sitemap";
import starlight from "@astrojs/starlight";
import starlightDocSearch from "@astrojs/starlight-docsearch";
import vercel from "@astrojs/vercel";
import { codecovVitePlugin } from "@codecov/vite-plugin";
import tailwindcss from "@tailwindcss/vite";
import { defineConfig, envField, fontProviders } from "astro/config";
import favicons from "astro-favicons";
import icon from "astro-icon";
import mermaid from "astro-mermaid";
import rehypeKatex from "rehype-katex";
import rehypeRaw from "rehype-raw";
import remarkMath from "remark-math";
import starlightImageZoom from "starlight-image-zoom";
import starlightLinksValidatorOriginal from "starlight-links-validator";
import starlightLlmsTxt from "starlight-llms-txt";

/**
 * Wraps `starlight-links-validator` so broken-link errors are surfaced as
 * warnings instead of failing the build. The validator already logs each
 * broken link before throwing, so catching the throw preserves the report
 * while keeping CI (and local `pnpm build`) from exiting non-zero.
 *
 * @type {typeof starlightLinksValidatorOriginal}
 */
function starlightLinksValidator(options) {
  const plugin = starlightLinksValidatorOriginal(options);
  const originalConfigSetup = plugin.hooks["config:setup"];
  if (!originalConfigSetup) return plugin;
  return {
    ...plugin,
    hooks: {
      ...plugin.hooks,
      "config:setup"(context) {
        return originalConfigSetup({
          ...context,
          addIntegration(integration) {
            const buildDone = integration.hooks?.["astro:build:done"];
            if (!buildDone) return context.addIntegration(integration);
            return context.addIntegration({
              ...integration,
              hooks: {
                ...integration.hooks,
                "astro:build:done": async (params) => {
                  try {
                    await buildDone(params);
                  } catch (error) {
                    const message = error instanceof Error ? error.message : String(error);
                    context.logger.warn(
                      `starlight-links-validator: ${message} (downgraded to warning; build continues)`,
                    );
                  }
                },
              },
            });
          },
        });
      },
    },
  };
}

import starlightOpenAPI from "starlight-openapi";
import { sidebar } from "./astro.sidebar.ts";
import { cspConfig } from "./src/config/csp";
import { SITE_TITLES, SUPPORTED_LANGUAGES } from "./src/config/i18n";
import onDemandDirective from "./src/integrations/client-on-demand/register.js";
import { devServerFileWatcher } from "./src/integrations/dev-server-file-watcher";
import { firebaseIntegration } from "./src/integrations/firebase";
import { llmsTxtIndex } from "./src/integrations/llms-txt-index";
import { monacoEditorIntegration } from "./src/integrations/monacoEditor";
import { ogImagesIntegration } from "./src/integrations/ogImages";
import { ENV } from "./src/lib/env";
import { remarkClientOnly } from "./src/plugins";

const ALGOLIA_APP_ID = ENV.ALGOLIA_APP_ID;
const ALGOLIA_SEARCH_API_KEY = ENV.ALGOLIA_SEARCH_API_KEY;
const ALGOLIA_INDEX_NAME = ENV.ALGOLIA_INDEX_NAME;

const hasAlgoliaConfig = ALGOLIA_APP_ID && ALGOLIA_SEARCH_API_KEY && ALGOLIA_INDEX_NAME;
const enableApiReference = true;

/** @type {(config: import("vite").UserConfig) => boolean} */
const isClientViteBuild = (config) => !config.build?.ssr;
/** @type {(config: import("vite").UserConfig) => boolean} */
const isServerViteBuild = (config) => Boolean(config.build?.ssr);

// https://astro.build/config
export default defineConfig({
  build: {
    inlineStylesheets: "never",
  },
  site:
    ENV.VERCEL_ENV === "production"
      ? "https://aptos.dev"
      : ENV.VERCEL_URL
        ? `https://${ENV.VERCEL_URL}`
        : "http://localhost:4321",
  trailingSlash: "never",
  integrations: [
    monacoEditorIntegration(),
    // Custom client directive for on-demand loading
    onDemandDirective(),
    // Mermaid diagram support
    mermaid(),
    // Only include devServerFileWatcher in development mode
    ...(process.env.NODE_ENV === "development" || !process.env.VERCEL
      ? [
          devServerFileWatcher([
            "./integrations/*", // Custom integrations
            "./astro.sidebar.ts", // Sidebar configuration file
            "./src/content/nav/*.ts", // Sidebar labels
          ]),
        ]
      : []),
    ogImagesIntegration(),
    firebaseIntegration(),
    starlight({
      title: SITE_TITLES,
      logo: {
        light: "~/assets/aptos-logomark-light.svg",
        dark: "~/assets/aptos-logomark-dark.svg",
        replacesTitle: false,
      },
      editLink: {
        baseUrl: "https://github.com/aptos-labs/aptos-docs/edit/main/",
      },
      lastUpdated: true,
      expressiveCode: {
        shiki: {
          // Define langs for shiki syntax highlighting
          langAlias: {
            csharp: "csharp",
            go: "go",
            json: "json",
            kotlin: "kotlin",
            move: "move",
            powershell: "powershell",
            python: "python",
            rust: "rust",
            swift: "swift",
            terraform: "terraform",
            toml: "toml",
            tsx: "tsx",
            yaml: "yaml",
          },
        },
      },
      defaultLocale: "root", // optional
      locales: Object.fromEntries(
        SUPPORTED_LANGUAGES.map(({ code, label }) => [
          code === "en" ? "root" : code, // Use "root" for English
          { label, lang: code },
        ]),
      ),
      social: [
        { label: "GitHub", icon: "github", href: "https://github.com/aptos-labs" },
        { label: "X", icon: "x.com", href: "https://x.com/aptos" },
        { label: "Discord", icon: "discord", href: "https://discord.com/invite/aptosnetwork" },
        //{ label: "Forum", icon: "discourse", href: "https://forum.aptosfoundation.org" },
        //{ label: "Reddit", icon: "reddit", href: "https://www.reddit.com/r/Aptos" },
        { label: "Telegram", icon: "telegram", href: "https://t.me/aptos" },
      ],
      components: {
        Head: "./src/starlight-overrides/Head.astro",
        Header: "./src/starlight-overrides/Header.astro",
        Hero: "./src/starlight-overrides/Hero.astro",
        LanguageSelect: "./src/starlight-overrides/LanguageSelect.astro",
        MobileMenuToggle: "./src/starlight-overrides/MobileMenuToggle.astro",
        PageFrame: "./src/starlight-overrides/PageFrame.astro",
        PageSidebar: "./src/starlight-overrides/PageSidebar.astro",
        PageTitle: "./src/starlight-overrides/PageTitle.astro",
        Sidebar: "./src/starlight-overrides/Sidebar.astro",
        TwoColumnContent: "./src/starlight-overrides/TwoColumnContent.astro",
      },
      plugins: [
        starlightImageZoom(),
        starlightLinksValidator({
          errorOnFallbackPages: false,
          errorOnInconsistentLocale: true,
          sameSitePolicy: "validate",
          errorOnInvalidHashes: false,
          errorOnLocalLinks: false,
          exclude: ({ file, link, slug }) => {
            // Exclude autogenerated content and non-translatable static resources
            const excludePaths = ["/rest-api", "/move-reference", "/gas-profiling", "/scripts"];

            // Aptos Learn workshop mirrors are imported content, not authored in this repo.
            // Their internal links are validated upstream in the Learn source, so keep them
            // out of the docs-site validator here to avoid false positives on generated pages.
            if (
              file.includes("/build/guides/ethereum-to-aptos/") ||
              slug.includes("/build/guides/ethereum-to-aptos/")
            ) {
              return true;
            }

            // Plain-text LLM exports (injected routes; no HTML page for the validator to crawl)
            if (link.includes("/llms-small.txt") || link.includes("/llms-full.txt")) {
              return true;
            }

            // Known `.well-known/` endpoints served from `public/` or via a Vercel
            // redirect. They are not doc routes, so starlight-links-validator can't
            // resolve them. List each one explicitly (rather than excluding the
            // whole `.well-known/` prefix) so a typo in a docs page is still caught.
            const knownWellKnown = [
              "/.well-known/llms.txt",
              "/.well-known/api-catalog",
              "/.well-known/mcp/server-card.json",
              "/.well-known/agent-skills/index.json",
              "/.well-known/oauth-protected-resource",
              "/.well-known/openid-configuration",
              "/.well-known/oauth-authorization-server",
            ];
            if (knownWellKnown.some((path) => link.endsWith(path))) {
              return true;
            }

            // Exclude specific problematic links from external move-reference content
            const excludeLinks = ["https://aptos.dev/standards"];

            return (
              excludePaths.some((path) => link.includes(path)) ||
              excludeLinks.some((url) => url === link)
            );
          },
        }),
        // Registers /llms.txt, /llms-small.txt, /llms-full.txt routes; local handlers override output
        // (see src/integrations/llms-txt-index.ts). Curation lives in src/lib/llms-curated-ids.ts + src/lib/llms.ts.
        starlightLlmsTxt({
          rawContent: true,
        }),
        ...(hasAlgoliaConfig
          ? [
              starlightDocSearch({
                clientOptionsModule: "./src/config/docsearch.ts",
              }),
            ]
          : []),
        // Generate the OpenAPI documentation pages if enabled
        ...(enableApiReference
          ? [
              starlightOpenAPI(
                [
                  {
                    base: "rest-api",
                    label: "REST API Reference",
                    schema: "./public/aptos-spec.json",
                    sidebarMethodBadges: true,
                  },
                ],
                {
                  routeEntrypoint: "./src/components/OpenAPI/Route.astro",
                },
              ),
            ]
          : []),
      ],
      sidebar,
      customCss: ["./src/styles/global.css", "katex/dist/katex.min.css"],
    }),
    // Override the starlight-llms-txt plugin's generated llms routes with
    // local handlers so we can curate the index and tune the small/full exports.
    // Must be after Starlight so our injected routes take priority.
    llmsTxtIndex(),
    sitemap({
      serialize(item) {
        item.lastmod = new Date().toISOString();
        return item;
      },
      i18n: {
        defaultLocale: SUPPORTED_LANGUAGES.find((lang) => lang.default)?.code || "en",
        locales: Object.fromEntries(SUPPORTED_LANGUAGES.map(({ code }) => [code, code])),
      },
    }),
    partytown({
      config: {
        forward: ["dataLayer.push", "gtag"],
      },
    }),
    react({
      experimentalReactChildren: true,
      include: ["**/GraphQLEditor.tsx", "**/chat-widget/**/*.tsx"],
    }),
    favicons({
      name: "Aptos Docs",
      name_localized: SITE_TITLES,
      short_name: "Aptos",
      icons: {
        android: true,
        appleIcon: true,
        appleStartup: true,
        favicons: false,
        windows: true,
        yandex: true,
      },
    }),
    icon({
      include: {
        ph: [
          "rocket-launch",
          "hard-drives",
          "crane-tower",
          "brackets-curly",
          "file-text",
          "book-open",
          "circle-dashed",
          "lightning",
          "terminal",
          "globe-simple",
          "robot",
          "star",
          "pencil",
        ],
      },
    }),
  ],
  adapter: process.env.VERCEL
    ? vercel({
        staticHeaders: {
          cspMode: "global",
        },
        edgeMiddleware: false,
        imageService: true,
        imagesConfig: {
          domains: [],
          sizes: [320, 640, 1280],
          formats: ["image/avif", "image/webp"],
        },
      })
    : node({
        mode: "standalone",
        staticHeaders: true,
      }),
  vite: {
    plugins: [
      tailwindcss(),
      ...codecovVitePlugin({
        enableBundleAnalysis: Boolean(process.env.CODECOV_TOKEN),
        bundleName: "aptos-docs-client",
        uploadToken: process.env.CODECOV_TOKEN || undefined,
      }).map((p) => ({ ...p, apply: isClientViteBuild })),
      ...codecovVitePlugin({
        enableBundleAnalysis: Boolean(process.env.CODECOV_TOKEN),
        bundleName: "aptos-docs-server",
        uploadToken: process.env.CODECOV_TOKEN || undefined,
      }).map((p) => ({ ...p, apply: isServerViteBuild })),
    ],
    optimizeDeps: {
      exclude: ["@rollup/browser"],
    },
    resolve: {
      alias: {
        "~/images": fileURLToPath(new URL("./src/assets/images", import.meta.url)),
      },
    },
    build: {
      rollupOptions: {
        output: {
          manualChunks(id) {
            // Split Firebase into its own chunk for better caching
            if (id.includes("@firebase")) {
              return "vendor-firebase";
            }
            // Split React ecosystem into its own chunk
            if (
              id.includes("node_modules/react/") ||
              id.includes("node_modules/react-dom/") ||
              id.includes("node_modules/react-markdown/") ||
              id.includes("node_modules/react-syntax-highlighter/")
            ) {
              return "vendor-react";
            }
            return undefined;
          },
        },
      },
    },
  },
  markdown: {
    remarkPlugins: [
      remarkMath,
      [
        remarkClientOnly,
        {
          components: {
            GraphQLEditor: "react",
            Faucet: "react",
          },
        },
      ],
    ],
    rehypePlugins: [rehypeRaw, rehypeKatex],
  },
  prefetch: true,
  image: {
    domains: ["preview.aptos.dev", "aptos.dev"],
    remotePatterns: [{ protocol: "https" }],
  },
  env: {
    schema: {
      ALGOLIA_APP_ID: envField.string({
        context: "client",
        access: "public",
        optional: !hasAlgoliaConfig,
      }),
      ALGOLIA_SEARCH_API_KEY: envField.string({
        context: "client",
        access: "public",
        optional: !hasAlgoliaConfig,
      }),
      ALGOLIA_INDEX_NAME: envField.string({
        context: "client",
        access: "public",
        optional: !hasAlgoliaConfig,
      }),
      GITHUB_TOKEN: envField.string({
        context: "server",
        access: "secret",
        optional: true,
      }),
      GTAG_ID: envField.string({ context: "client", access: "public", optional: true }),
      ENABLE_API_REFERENCE: envField.string({
        context: "server",
        access: "public",
        optional: true,
        default: "true",
      }),
      ENABLE_MOVE_REFERENCE: envField.string({
        context: "server",
        access: "public",
        optional: true,
        default: "false",
      }),
    },
    validateSecrets: true,
  },
  security: {
    csp: cspConfig,
  },
  fonts: [
    {
      provider: fontProviders.local(),
      name: "Atkinson Hyperlegible Next",
      cssVariable: "--font-atkinson-hyperlegible-next",
      optimizedFallbacks: false,
      options: {
        variants: [
          {
            weight: "200 800",
            style: "normal",
            src: ["./src/assets/fonts/AtkinsonHyperlegibleNext-VariableFont_wght.woff2"],
            variationSettings: "normal",
            display: "swap",
          },
          {
            weight: "200 800",
            style: "italic",
            src: ["./src/assets/fonts/AtkinsonHyperlegibleNext-Italic-VariableFont_wght.woff2"],
            variationSettings: "normal",
            display: "swap",
          },
        ],
      },
    },
  ],
  redirects: {
    /**
     * Development-only redirects when Move Reference is disabled
     * NOTE: Use caution - 301 redirects may be cached by browsers
     * TODO: Needs further testing
     */
    // ...isMoveReferenceEnabled() ? {} : {
    //   "/move-reference/[network]": { src: "/move-reference/[network]", destination: "/move-reference", status: 301 },
    //   "/move-reference/[network]/[framework]": { src: "/move-reference/[network]/[framework]", destination: "/move-reference", status: 301 },
    //   "/move-reference/[network]/[framework]/[slug]": { src: "/move-reference/[network]/[framework]/[slug]", destination: "/move-reference", status: 301 },
    // },
    //"/build/smart-contracts/move-reference": {
    //  destination: "/move-reference",
    //  status: 301,
    //},
  },
});