Merge pull request #117 from USACE-RMC/enhancement/centralize-doc-config

Centralize doc flags and exclude inactive docs from prod build

Author: AdamGohs

docusaurus.config.js

@@ -3,6 +3,14 @@ import remarkGfm from 'remark-gfm';
 import remarkMath from 'remark-math';
 
 import path from 'path';
+import { createRequire } from 'module';
+
+// Load the CommonJS docConfig for the prod-mode exclude list. The docs plugin
+// is happy with glob patterns; we expand each inactive doc_location to a
+// "**/*" glob so every nested MDX under it is excluded from the build.
+const require = createRequire(import.meta.url);
+const { getInactiveDocLocations } = require('./src/docConfig');
+const inactiveDocExcludes = process.env.DOCS_MODE === 'prod' ? getInactiveDocLocations().map((loc) => `${loc}/**`) : [];
 
 // Normalize the drive letter to uppercase on Windows to prevent webpack
 // "modules with names that only differ in casing" warnings.
@@ -69,6 +77,7 @@ export default {
           remarkPlugins: [remarkMath, remarkGfm],
           rehypePlugins: [rehypeKatex],
           breadcrumbs: true,
+          exclude: inactiveDocExcludes,
         },
         theme: {
           customCss: normalizeDriveLetter(require.resolve('./src/css/custom.css')),

package-lock.json

@@ -10,8 +10,8 @@
     "report-map": "node scripts/generateReportIdMap.js",
     "generate-toc": "node scripts/generateEventTreeTOC.js",
     "image-dims": "node scripts/generateImageDimensions.js",
-    "start": "npm run image-dims && npm run report-map && npm run sidebars && npm run counters && npm run versions && npm run generate-toc && docusaurus start",
-    "build": "npm run image-dims && npm run report-map && npm run sidebars && npm run counters && npm run versions && npm run generate-toc && docusaurus build",
+    "start": "cross-env DOCS_MODE=dev npm run image-dims && cross-env DOCS_MODE=dev npm run report-map && cross-env DOCS_MODE=dev npm run sidebars && cross-env DOCS_MODE=dev npm run counters && cross-env DOCS_MODE=dev npm run versions && cross-env DOCS_MODE=dev npm run generate-toc && cross-env DOCS_MODE=dev docusaurus start",
+    "build": "cross-env DOCS_MODE=prod npm run image-dims && cross-env DOCS_MODE=prod npm run report-map && cross-env DOCS_MODE=prod npm run sidebars && cross-env DOCS_MODE=prod npm run counters && cross-env DOCS_MODE=prod npm run versions && cross-env DOCS_MODE=prod npm run generate-toc && cross-env DOCS_MODE=prod docusaurus build",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",
     "clear": "docusaurus clear",
@@ -51,6 +51,7 @@
     "@tailwindcss/postcss": "^4.1.11",
     "autoprefixer": "^10.4.21",
     "baseline-browser-mapping": "^2.9.19",
+    "cross-env": "^7.0.3",
     "postcss": "^8.5.6",
     "prettier": "^3.6.2",
     "prettier-plugin-tailwindcss": "^0.6.14"

package.json

@@ -1,6 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 const reportIdMap = require('../src/reportIdMap'); // Importing the map correctly
+const { shouldExcludeFromBuild } = require('../src/docConfig');
 
 // Base paths
 const docsBasePath = path.join(__dirname, '../docs');
@@ -172,6 +173,12 @@ const allDocPaths = findAllDocumentPaths(docsBasePath);
 
 for (const docPath of allDocPaths) {
   const normalizedDocPath = normalizePath(docPath); // Normalize path here
+
+  // In prod, skip counters generation for docs flagged inactive in
+  // src/docConfig.js — they won't be in the build, so the counters would be
+  // dead weight.
+  if (shouldExcludeFromBuild(normalizedDocPath)) continue;
+
   const reportId = reportIdMap[normalizedDocPath];
 
   if (reportId) {

scripts/counters.js

@@ -2,6 +2,7 @@
 
 const fs = require("fs");
 const path = require("path");
+const { shouldExcludeFromBuild } = require("../src/docConfig");
 
 const DOCS_PATH = path.join(__dirname, "../docs");
 const OUTPUT_FILE = path.join(__dirname, "../src/reportIdMap.js");
@@ -26,12 +27,17 @@ function walkDocs(currentPath, relPath = []) {
         const subHub = relPath[relPath.length - 2]; // One level above documentName
 
         const docPath = newRelPath.join("/");
+        const docBasePath = relPath.join("/"); // Path without the version suffix
 
         if (!subHub || !documentName) {
           console.warn(`⚠️ Skipping: Incomplete path at ${docPath}`);
           return;
         }
 
+        // In prod, skip docs flagged inactive in src/docConfig.js so report
+        // IDs aren't generated for content that won't exist in the build.
+        if (shouldExcludeFromBuild(docBasePath)) return;
+
         const reportId = `${subHub}-${documentName}-${version}`;
         reportIdMap[docPath] = reportId;
 

scripts/generateReportIdMap.js

@@ -14,6 +14,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { shouldExcludeFromBuild } = require('../src/docConfig');
 
 const DOCS_DIR = path.join(__dirname, '..', 'docs');
 const SIDEBAR_PATH = path.join(__dirname, '..', 'sidebars.js');
@@ -593,6 +594,10 @@ function generateSidebars() {
 
     const docPath = versionMatch[1];
     const version = versionMatch[2];
+
+    // In prod, skip docs flagged inactive in src/docConfig.js so the sidebar
+    // doesn't reference doc IDs that the docs plugin will exclude.
+    if (shouldExcludeFromBuild(docPath)) return;
     const docParts = docPath.split('/');
     const docGroup = docParts[1]; // e.g., "rmc-totalrisk"
     const folderName = docParts[docParts.length - 1]; // e.g., "applications-guide"

scripts/generateSidebars.js

@@ -1,5 +1,6 @@
 const fs = require('fs');
 const path = require('path');
+const { shouldExcludeFromBuild } = require('../src/docConfig');
 
 // Define the base path for your docs folder
 const docsFolderPath = path.join(__dirname, '..', 'docs');
@@ -106,16 +107,20 @@ function generateVersions() {
     }
   });
 
-  // Convert keys to forward slashes
+  // Convert keys to forward slashes; in prod mode, drop inactive docs entirely
+  // so they don't appear in latestVersions, versionList, or the Algolia
+  // crawler config.
   const updatedLatestVersions = {};
   const updatedAllVersions = {};
 
   for (const key in latestVersions) {
     const newKey = key.replace(/\\/g, '/');
+    if (shouldExcludeFromBuild(newKey)) continue;
     updatedLatestVersions[newKey] = latestVersions[key];
   }
   for (const key in allVersions) {
     const newKey = key.replace(/\\/g, '/');
+    if (shouldExcludeFromBuild(newKey)) continue;
     updatedAllVersions[newKey] = allVersions[key];
   }
 

scripts/versions.js

@@ -37,6 +37,18 @@ const ContentBubble = ({
     pointer-events-none cursor-not-allowed
   `;
 
+  // In dev, allow inactive ("Coming Soon") tiles to be clickable so contributors
+  // can preview docs they're working on without flipping the active flag. In
+  // prod, the tile remains a non-clickable visual placeholder. Webpack injects
+  // process.env.NODE_ENV at build time: 'development' for `npm start`,
+  // 'production' for `npm run build`.
+  const isDevPreviewable = !active && process.env.NODE_ENV === 'development' && (doc_location || downloadUrl);
+  const inactiveDevClasses = `
+    coming-soon-gradient-card
+    hover:scale-[1.02]
+    cursor-pointer
+  `;
+
   // Build <ThemedImage /> sources, with fallback to legacy `icon`
   const sources = iconLight || icon ? { light: iconLight ?? icon, dark: iconDark ?? iconLight ?? icon } : null;
 
@@ -74,11 +86,23 @@ const ContentBubble = ({
     );
   }
 
-  return active ? (
-    <a href={doc_location} className={`${baseClasses} ${activeClasses}`}>
-      <Inner isDraft={draft} />
-    </a>
-  ) : (
+  if (active) {
+    return (
+      <a href={doc_location} className={`${baseClasses} ${activeClasses}`}>
+        <Inner isDraft={draft} />
+      </a>
+    );
+  }
+
+  if (isDevPreviewable) {
+    return (
+      <a href={downloadUrl ?? doc_location} className={`${baseClasses} ${inactiveDevClasses}`} {...(downloadUrl ? { download: true } : {})}>
+        <Inner comingSoon isDraft={draft} />
+      </a>
+    );
+  }
+
+  return (
     <div className={`${baseClasses} ${inactiveClasses}`}>
       <Inner comingSoon />
     </div>