ci(docs): add dedicated pdf builds for performance

omargfh · omargfh · commit 154075e693ee · 2026-03-02T14:21:49.000-06:00
diff --git a/apps/docs/.env b/apps/docs/.env
@@ -11,6 +11,6 @@ VERSIONS_SRC="/versions.json"
 REPO_ROOT=../..
 EXTENSIONS_DIR="$REPO_ROOT/external/extensions"
 
-BUILD_LATEST=true
+BUILD_LATEST=${BUILD_LATEST:-true}
 BUILD_REPO="git@github.com:NetLogo/docs.git"
 BUILD_BRANCH="main"
diff --git a/apps/docs/nuxt.config.pdf.ts b/apps/docs/nuxt.config.pdf.ts
@@ -0,0 +1,43 @@
+import { getRoutesSubset } from '@repo/netlogo-docs/helpers';
+import type { DefineNuxtConfig } from 'nuxt/config';
+
+const pdfOverrides: Parameters<DefineNuxtConfig>[0] = {
+  routeRules: {
+    '/**': { isr: 3600 },
+  },
+
+  linkChecker: {
+    enabled: false,
+  },
+
+  sitemap: {
+    enabled: false,
+  },
+
+  gtag: {
+    enabled: false,
+  },
+
+  contentAssets: {
+    debug: false,
+  },
+
+  ogImage: {
+    defaults: {
+      extension: 'png',
+      width: 400,
+      height: 600,
+    },
+  },
+
+  nitro: {
+    prerender: {
+      autoSubfolderIndex: false,
+      crawlLinks: false,
+      concurrency: 20,
+      routes: await getRoutesSubset(process.env.NITRO_PRERENDER_ROUTES?.split(',').map((route) => route.trim()) || []),
+    },
+  },
+};
+
+export default pdfOverrides;
diff --git a/apps/docs/nuxt.config.ts b/apps/docs/nuxt.config.ts
@@ -1,3 +1,4 @@
+import { deepMerge } from '@repo/utils/std/objects';
 import tailwindcss from '@tailwindcss/vite';
 
 import { getDocumentedExtensionBuilders } from '@repo/netlogo-docs/extension-docs';
@@ -7,166 +8,183 @@ import autogenConfig from './lib/docs/autogen.config';
 import * as MarkdownConfig from './lib/docs/markdown.config';
 import runDocsAutogen from './lib/docs/runDocsAutogen';
 
+import type { DefineNuxtConfig } from 'nuxt/config';
 import { publicEnvironmentVariables, verifyEnvironmentVariables } from './env.public';
+import pdfOverrides from './nuxt.config.pdf';
 import { vueUiSrc, vueUiStyles } from './turbo';
 
+type NuxtConfigInput = Parameters<DefineNuxtConfig>[0];
 const basePath = process.env['BASE_PATH'] ?? '/';
 
-// https://nuxt.com/docs/api/configuration/nuxt-config
-export default defineNuxtConfig({
-  compatibilityDate: '2025-07-15',
-  app: {
-    baseURL: basePath,
-    rootId: '__netlogo',
-  },
-  devtools: { enabled: true },
-  ssr: true,
-  // prettier-ignore
-  modules: [
-    '@nuxtjs/sitemap',             // Adds sitemap.xml
-    '@repo/nuxt-content-assets',   // Local asset loading based on relative paths in Markdowns
-    '@nuxt/content',               // Query, navigation, search, and rendering of Markdown files
-    '@nuxt/ui',                    // Reka-UI library for Nuxt
-    '@nuxt/icon',                  // Optimized icons with iconify
-    'nuxt-svgo',                   // SVG loader from file
-    '@nuxt/eslint',                // Linter
-    'nuxt-gtag',                   // Google
-    'nuxt-og-image',               // Dynamic Open Graph image generation
-    'nuxt-link-checker',           // Link checking post-build
-  ],
-  site: { url: 'https://docs.netlogo.org', name: process.env['PRODUCT_NAME'] },
-  css: ['~/assets/styles/main.scss', '~/assets/styles/tailwind.css', vueUiStyles],
-  colorMode: {
-    preference: 'light',
-  },
-
-  gtag: {
-    id: 'G-ZET3KSPLMC',
-  },
-
-  imports: {
-    autoImport: true,
-    transform: {
-      exclude: [/\bnode_modules\b/, /\b\.git\b/],
-    },
-  },
+const isUsingPdfConfig = process.env['DOCS_ENV_PDF'] === '1';
+const optionalPdfLayer = isUsingPdfConfig ? pdfOverrides : {};
 
-  $development: {
-    experimental: {
-      payloadExtraction: false,
-    },
-  },
+if (isUsingPdfConfig) {
+  console.info('[repo] Running with PDF generation configuration overrides');
+}
 
-  icon: {
-    mode: 'css',
-    cssLayer: 'base',
-  },
+// https://nuxt.com/docs/api/configuration/nuxt-config
 
-  components: [
+export default defineNuxtConfig(
+  deepMerge<NuxtConfigInput, NuxtConfigInput>(
     {
-      path: vueUiSrc,
-      global: true,
-      pattern: '**/*.vue',
-      ignore: ['**/examples/*.vue', '**/tests/*.vue'],
-      pathPrefix: false,
-      watch: true,
-    },
-    {
-      path: '~/components',
-      global: true,
-      pattern: '**/*.vue',
-      ignore: ['**/examples/*.vue', '**/tests/*.vue'],
-      pathPrefix: false,
-      watch: true,
-    },
-  ],
+      compatibilityDate: '2025-07-15',
+      app: {
+        baseURL: basePath,
+        rootId: '__netlogo',
+      },
+      devtools: { enabled: true },
+      ssr: true,
+      // prettier-ignore
+      modules: [
+        '@nuxtjs/sitemap',             // Adds sitemap.xml
+        '@repo/nuxt-content-assets',   // Local asset loading based on relative paths in Markdowns
+        '@nuxt/content',               // Query, navigation, search, and rendering of Markdown files
+        '@nuxt/ui',                    // Reka-UI library for Nuxt
+        '@nuxt/icon',                  // Optimized icons with iconify
+        'nuxt-svgo',                   // SVG loader from file
+        '@nuxt/eslint',                // Linter
+        'nuxt-gtag',                   // Google
+        'nuxt-og-image',               // Dynamic Open Graph image generation
+        'nuxt-link-checker',           // Link checking post-build
+      ],
+      site: { url: 'https://docs.netlogo.org', name: process.env['PRODUCT_NAME'] },
+      css: ['~/assets/styles/main.scss', '~/assets/styles/tailwind.css', vueUiStyles],
+      colorMode: {
+        preference: 'light',
+      },
 
-  ignore: ['.build/', '.latest/', '.static/', '.preview/'],
+      gtag: {
+        id: 'G-ZET3KSPLMC',
+      },
 
-  svgo: {
-    customComponent: 'SvgImport',
-  },
+      imports: {
+        autoImport: true,
+        transform: {
+          exclude: [/\bnode_modules\b/, /\b\.git\b/],
+        },
+      },
 
-  vite: {
-    plugins: [tailwindcss()],
-    optimizeDeps: {
-      include: ['@repo/vue-ui', ...MarkdownConfig.externalImports],
-    },
-    server: {
-      hmr: {
-        overlay: true,
+      $development: {
+        experimental: {
+          payloadExtraction: false,
+        },
       },
-      watch: { usePolling: true },
-    },
-  },
 
-  content: {
-    build: MarkdownConfig.buildOptions,
-    renderer: {
-      anchorLinks: false,
-    },
-    watch: { enabled: false },
-  },
-
-  contentAssets: {
-    imageSize: 'style attrs',
-    contentExtensions: 'md',
-    debug: true,
-    overrideStaticDimensions: false,
-  },
-
-  ogImage: {
-    defaults: {
-      extension: 'jpeg',
-      sharp: {
-        quality: 70,
+      icon: {
+        mode: 'css',
+        cssLayer: 'base',
       },
-    },
-  },
 
-  linkChecker: {
-    excludeLinks: ['/*.pdf', `${basePath}NetLogo_User_Manual.pdf`],
-    skipInspections: ['no-baseless', 'no-underscores', 'trailing-slash'],
-    report: {
-      html: process.env['CHECK'] === 'true',
-    },
-  },
-
-  runtimeConfig: {
-    public: {
-      extensions: (await getDocumentedExtensionBuilders(autogenConfig)).map((ext) => ({
-        title: ext.fullName,
-        href: `/${ext.name.toLowerCase()}`,
-      })),
-      ...publicEnvironmentVariables,
-    },
-  },
+      components: [
+        {
+          path: vueUiSrc,
+          global: true,
+          pattern: '**/*.vue',
+          ignore: ['**/examples/*.vue', '**/tests/*.vue'],
+          pathPrefix: false,
+          watch: true,
+        },
+        {
+          path: '~/components',
+          global: true,
+          pattern: '**/*.vue',
+          ignore: ['**/examples/*.vue', '**/tests/*.vue'],
+          pathPrefix: false,
+          watch: true,
+        },
+      ],
+
+      ignore: ['.build/', '.latest/', '.static/', '.preview/'],
+
+      svgo: {
+        customComponent: 'SvgImport',
+      },
 
-  hooks: {
-    async ready() {
-      verifyEnvironmentVariables();
+      vite: {
+        plugins: [tailwindcss()],
+        optimizeDeps: {
+          include: ['@repo/vue-ui', ...MarkdownConfig.externalImports],
+        },
+        server: {
+          hmr: {
+            overlay: true,
+          },
+          watch: { usePolling: true },
+        },
+      },
 
-      console.info(`[repo] Using @repo/vue-ui source path: ${vueUiSrc}`);
-      console.info(`[repo] Using @repo/vue-ui styles path: ${vueUiStyles}`);
+      content: {
+        build: MarkdownConfig.buildOptions,
+        renderer: {
+          anchorLinks: false,
+        },
+        watch: { enabled: false },
+      },
 
-      const noAutogen = process.env['NO_AUTOGEN'] === 'true';
-      if (noAutogen === true) return;
-      await runDocsAutogen();
-    },
-    'content:file:beforeParse'(ctx) {
-      addNuxtContentAssetsRoot(ctx.file);
-    },
-  },
-
-  nitro: {
-    static: true,
-    serveStatic: true,
-    baseURL: basePath,
-    prerender: {
-      autoSubfolderIndex: false,
-      crawlLinks: true,
-      concurrency: 1,
-      routes: await getRoutes(),
+      contentAssets: {
+        imageSize: 'style attrs',
+        contentExtensions: 'md',
+        debug: true,
+        overrideStaticDimensions: false,
+      },
+
+      ogImage: {
+        defaults: {
+          extension: 'jpeg',
+          sharp: {
+            quality: 70,
+          },
+        },
+      },
+
+      linkChecker: {
+        excludeLinks: ['/*.pdf', `${basePath}NetLogo_User_Manual.pdf`],
+        skipInspections: ['no-baseless', 'no-underscores', 'trailing-slash'],
+        report: {
+          html: process.env['CHECK'] === 'true',
+        },
+      },
+
+      runtimeConfig: {
+        public: {
+          extensions: (await getDocumentedExtensionBuilders(autogenConfig)).map((ext) => ({
+            title: ext.fullName,
+            href: `/${ext.name.toLowerCase()}`,
+          })),
+          ...publicEnvironmentVariables,
+        },
+      },
+
+      hooks: {
+        async ready() {
+          verifyEnvironmentVariables();
+
+          console.info(`[repo] Using @repo/vue-ui source path: ${vueUiSrc}`);
+          console.info(`[repo] Using @repo/vue-ui styles path: ${vueUiStyles}`);
+
+          const noAutogen = process.env['NO_AUTOGEN'] === 'true';
+          if (noAutogen === true) return;
+          await runDocsAutogen();
+        },
+        'content:file:beforeParse'(ctx) {
+          addNuxtContentAssetsRoot(ctx.file);
+        },
+      },
+
+      nitro: {
+        static: true,
+        serveStatic: true,
+        baseURL: basePath,
+        prerender: {
+          autoSubfolderIndex: false,
+          crawlLinks: true,
+          concurrency: 1,
+          routes: await getRoutes(),
+        },
+      },
     },
-  },
-});
+    optionalPdfLayer,
+    { mergeArrays: false },
+  ),
+);
diff --git a/apps/docs/package.json b/apps/docs/package.json
@@ -12,6 +12,7 @@
     "docs:deploy": "bash ./scripts/deploy.sh",
     "docs:preview": "bash ./scripts/preview.sh",
     "docs:clean-up": "bash ./scripts/clean-up.sh",
+    "docs:build-and-generate-manual": "bash ./scripts/generate-manual/build-html.sh && yarn run docs:generate-manual",
     "docs:generate-manual": "bash ./scripts/generate-manual/run.sh",
     "docs:make-static-site": "bash ./scripts/make-static/run.sh .build/latest .build-static",
     "docs:all": "npm run docs:clean-up && npm run docs:build && npm run docs:generate-manual && npm run docs:deploy",
diff --git a/apps/docs/scripts/generate-manual/build-html.sh b/apps/docs/scripts/generate-manual/build-html.sh
@@ -0,0 +1,5 @@
+#!/bin/bash
+source .env
+source ${BASH_SOURCE%/*}/content
+
+DOCS_ENV_PDF=1 BUILD_LATEST=false ./scripts/generate.sh
diff --git a/apps/docs/scripts/generate-manual/run.sh b/apps/docs/scripts/generate-manual/run.sh
