docs.config.ts

import fs from "fs-extra";
import path from "path";
import {
  Version,
  MdxData,
  NonVersionedDocumentRootConfig,
  VersionedDocumentRootConfig,
  LinkValidator,
  MdxFileFilter,
  VersionsProvider,
  NonVersionedVariableProcessor
} from "@webiny/docs-generator";
import { DeveloperDocsMdxFile } from "./docs/developer-docs/DeveloperDocsMdxFile";
import { HandbookMdxFile } from "./docs/handbook/HandbookMdxFile";
import { UserGuideMdxFile } from "./docs/user-guides/UserGuideMdxFile";
import { UserGuidesVersionProvider } from "./docs/user-guides/UserGuidesVersionProvider";
import { ReleaseNotesMdxFile } from "./docs/release-notes/ReleaseNotesMdxFile";

// @ts-expect-error
import { redirects } from "./vercel.json";

const preview = process.env.VERCEL_ENV === "preview" || process.env.NODE_ENV === "development";

/**
 * Sometimes, we want to use links unknown to the LinkValidator, but which are located under the same domain.
 * Use this array to whitelist such links.
 * We also whitelist all links that are defined in `vercel.json` redirects.
 */
const linkWhitelist: string[] = [...redirects.map(r => r.source), "/forms/product-demo", "/slack"];

/**
 * If you want to only build specific versions in the Vercel preview deployment,
 * whitelist them by adding version numbers to this array. Example: "5.35.x"
 */
const whitelistedVersions: string[] = [];

/**
 * Only build versions at or above this version (e.g., "5.40.x").
 * Set via MIN_VERSION environment variable or modify here.
 * Set to empty string to build all versions.
 */
const minVersionToBuild = process.env.MIN_VERSION || "";

const filterByEnvironment = (version: Version) => {
  // In `preview`, if there are specific versions whitelisted for deployment, those are the only ones we'll output.
  if (preview && whitelistedVersions.length > 0) {
    return whitelistedVersions.includes(version.getValue());
  }

  // If minVersionToBuild is set, only build versions >= minVersion or `latest`.
  if (minVersionToBuild) {
    if (minVersionToBuild === "latest") {
      return version.isLatest();
    }
    const versionNum = parseFloat(version.getValue().replace(/[^\d.]/g, ""));
    const minVersionNum = parseFloat(minVersionToBuild.replace(/[^\d.]/g, ""));
    return versionNum >= minVersionNum;
  }

  // Build everything.
  return true;
};

const filterFilePathByVersion = (filePath: string): boolean => {
  // Extract version from file path (e.g., /docs/developer-docs/5.40.x/... or /docs/user-guides/5.40.x/...)
  const versionMatch = filePath.match(/\/(\d+\.\d+\.x)\//);

  if (!versionMatch) {
    // If no version in path, include the file (e.g., non-versioned docs)
    return true;
  }

  const versionString = versionMatch[1];

  // Use the same filtering logic as filterByEnvironment
  if (preview && whitelistedVersions.length > 0) {
    return whitelistedVersions.includes(versionString);
  }

  if (minVersionToBuild) {
    if (minVersionToBuild === "latest") {
      // For file paths, we can't determine if it's "latest" without more context
      // So we'll include all versioned files when minVersionToBuild is "latest"
      return true;
    }
    const versionNum = parseFloat(versionString.replace(/[^\d.]/g, ""));
    const minVersionNum = parseFloat(minVersionToBuild.replace(/[^\d.]/g, ""));
    return versionNum >= minVersionNum;
  }

  return true;
};

const existsInDocs = (link: string) => {
  return fs.pathExists(path.join(__dirname, `src/pages/${link}.js`));
};

export default {
  projectRootDir: __dirname,
  cleanOutputDir: [path.resolve("src/pages/docs"), path.resolve("public/raw/docs")],
  sitemapOutputPath: path.resolve("public/algolia/sitemap.xml"),
  linkValidator: new LinkValidator(
    linkWhitelist,
    link => {
      return existsInDocs(link);
    },
    filterFilePathByVersion
  ),
  documentRoots: [
    /* Developer Docs */
    new VersionedDocumentRootConfig({
      rootDir: path.resolve("docs/developer-docs"),
      linkPrefix: "/docs",
      outputDir: path.resolve("src/pages"),
      pageLayout: "@/layouts/DocumentationLayout",
      mdxFileFactory: (data: MdxData, version: Version) => new DeveloperDocsMdxFile(data, version),
      mdxFileOutputFilter: new MdxFileFilter<DeveloperDocsMdxFile>(mdxFile => {
        return filterByEnvironment(mdxFile.getVersion());
      })
    }),

    /* User Guides */
    new VersionedDocumentRootConfig({
      rootDir: path.resolve("docs/user-guides"),
      linkPrefix: "/docs",
      outputDir: path.resolve("src/pages"),
      pageLayout: "@/layouts/DocumentationLayout",
      mdxFileFactory: (data: MdxData, version: Version) => new UserGuideMdxFile(data, version),
      mdxFileOutputFilter: new MdxFileFilter<UserGuideMdxFile>(mdxFile => {
        return filterByEnvironment(mdxFile.getVersion());
      }),
      versionsProvider: new UserGuidesVersionProvider(
        path.resolve("docs/developer-docs"),
        path.resolve("docs/user-guides")
      )
    }),

    /* Release Notes */
    new NonVersionedDocumentRootConfig({
      rootDir: path.resolve("docs/release-notes"),
      linkPrefix: "/docs",
      outputDir: path.resolve("src/pages"),
      pageLayout: "@/layouts/ReleaseNotesLayout",
      mdxFileFactory: (data: MdxData) => new ReleaseNotesMdxFile(data),
      mdxFileProcessors: [
        new NonVersionedVariableProcessor(
          new VersionsProvider(path.resolve("docs/developer-docs")).getVersions()
        )
      ]
    }),

    /* Handbook */
    new NonVersionedDocumentRootConfig({
      rootDir: path.resolve("docs/handbook"),
      linkPrefix: "/docs/handbook",
      outputDir: path.resolve("src/pages"),
      pageLayout: "@/layouts/HandbookLayout",
      mdxFileFactory: (data: MdxData) => new HandbookMdxFile(data)
    })
  ]
};