Skip to content

Commit 475736d

Browse files
AdamGohsAdamGohs
committed
Centralize doc active/draft flags into src/docConfig.js
Inactive docs (active: false) are now excluded from the prod build, sidebar, and Algolia crawler config — preventing search results from unpublished documents like the LST Users Guide. Coming Soon tiles remain clickable in dev (DOCS_MODE=dev) so contributors can preview inactive docs without flipping the flag.
1 parent 0e7748a commit 475736d

21 files changed

Lines changed: 504 additions & 320 deletions

‎docusaurus.config.js‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,14 @@ import remarkGfm from 'remark-gfm';
33
import remarkMath from 'remark-math';
44

55
import path from 'path';
6+
import { createRequire } from 'module';
7+
8+
// Load the CommonJS docConfig for the prod-mode exclude list. The docs plugin
9+
// is happy with glob patterns; we expand each inactive doc_location to a
10+
// "**/*" glob so every nested MDX under it is excluded from the build.
11+
const require = createRequire(import.meta.url);
12+
const { getInactiveDocLocations } = require('./src/docConfig');
13+
const inactiveDocExcludes = process.env.DOCS_MODE === 'prod' ? getInactiveDocLocations().map((loc) => `${loc}/**`) : [];
614

715
// Normalize the drive letter to uppercase on Windows to prevent webpack
816
// "modules with names that only differ in casing" warnings.
@@ -69,6 +77,7 @@ export default {
6977
remarkPlugins: [remarkMath, remarkGfm],
7078
rehypePlugins: [rehypeKatex],
7179
breadcrumbs: true,
80+
exclude: inactiveDocExcludes,
7281
},
7382
theme: {
7483
customCss: normalizeDriveLetter(require.resolve('./src/css/custom.css')),

‎package-lock.json‎

Lines changed: 20 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,8 @@
1010
"report-map": "node scripts/generateReportIdMap.js",
1111
"generate-toc": "node scripts/generateEventTreeTOC.js",
1212
"image-dims": "node scripts/generateImageDimensions.js",
13-
"start": "npm run image-dims && npm run report-map && npm run sidebars && npm run counters && npm run versions && npm run generate-toc && docusaurus start",
14-
"build": "npm run image-dims && npm run report-map && npm run sidebars && npm run counters && npm run versions && npm run generate-toc && docusaurus build",
13+
"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",
14+
"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",
1515
"swizzle": "docusaurus swizzle",
1616
"deploy": "docusaurus deploy",
1717
"clear": "docusaurus clear",
@@ -51,6 +51,7 @@
5151
"@tailwindcss/postcss": "^4.1.11",
5252
"autoprefixer": "^10.4.21",
5353
"baseline-browser-mapping": "^2.9.19",
54+
"cross-env": "^7.0.3",
5455
"postcss": "^8.5.6",
5556
"prettier": "^3.6.2",
5657
"prettier-plugin-tailwindcss": "^0.6.14"

‎scripts/counters.js‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
const fs = require('fs');
22
const path = require('path');
33
const reportIdMap = require('../src/reportIdMap'); // Importing the map correctly
4+
const { shouldExcludeFromBuild } = require('../src/docConfig');
45

56
// Base paths
67
const docsBasePath = path.join(__dirname, '../docs');
@@ -172,6 +173,12 @@ const allDocPaths = findAllDocumentPaths(docsBasePath);
172173

173174
for (const docPath of allDocPaths) {
174175
const normalizedDocPath = normalizePath(docPath); // Normalize path here
176+
177+
// In prod, skip counters generation for docs flagged inactive in
178+
// src/docConfig.js — they won't be in the build, so the counters would be
179+
// dead weight.
180+
if (shouldExcludeFromBuild(normalizedDocPath)) continue;
181+
175182
const reportId = reportIdMap[normalizedDocPath];
176183

177184
if (reportId) {

‎scripts/generateReportIdMap.js‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
const fs = require("fs");
44
const path = require("path");
5+
const { shouldExcludeFromBuild } = require("../src/docConfig");
56

67
const DOCS_PATH = path.join(__dirname, "../docs");
78
const OUTPUT_FILE = path.join(__dirname, "../src/reportIdMap.js");
@@ -26,12 +27,17 @@ function walkDocs(currentPath, relPath = []) {
2627
const subHub = relPath[relPath.length - 2]; // One level above documentName
2728

2829
const docPath = newRelPath.join("/");
30+
const docBasePath = relPath.join("/"); // Path without the version suffix
2931

3032
if (!subHub || !documentName) {
3133
console.warn(`⚠️ Skipping: Incomplete path at ${docPath}`);
3234
return;
3335
}
3436

37+
// In prod, skip docs flagged inactive in src/docConfig.js so report
38+
// IDs aren't generated for content that won't exist in the build.
39+
if (shouldExcludeFromBuild(docBasePath)) return;
40+
3541
const reportId = `${subHub}-${documentName}-${version}`;
3642
reportIdMap[docPath] = reportId;
3743

‎scripts/generateSidebars.js‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414

1515
const fs = require('fs');
1616
const path = require('path');
17+
const { shouldExcludeFromBuild } = require('../src/docConfig');
1718

1819
const DOCS_DIR = path.join(__dirname, '..', 'docs');
1920
const SIDEBAR_PATH = path.join(__dirname, '..', 'sidebars.js');
@@ -593,6 +594,10 @@ function generateSidebars() {
593594

594595
const docPath = versionMatch[1];
595596
const version = versionMatch[2];
597+
598+
// In prod, skip docs flagged inactive in src/docConfig.js so the sidebar
599+
// doesn't reference doc IDs that the docs plugin will exclude.
600+
if (shouldExcludeFromBuild(docPath)) return;
596601
const docParts = docPath.split('/');
597602
const docGroup = docParts[1]; // e.g., "rmc-totalrisk"
598603
const folderName = docParts[docParts.length - 1]; // e.g., "applications-guide"

‎scripts/versions.js‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
const fs = require('fs');
22
const path = require('path');
3+
const { shouldExcludeFromBuild } = require('../src/docConfig');
34

45
// Define the base path for your docs folder
56
const docsFolderPath = path.join(__dirname, '..', 'docs');
@@ -106,16 +107,20 @@ function generateVersions() {
106107
}
107108
});
108109

109-
// Convert keys to forward slashes
110+
// Convert keys to forward slashes; in prod mode, drop inactive docs entirely
111+
// so they don't appear in latestVersions, versionList, or the Algolia
112+
// crawler config.
110113
const updatedLatestVersions = {};
111114
const updatedAllVersions = {};
112115

113116
for (const key in latestVersions) {
114117
const newKey = key.replace(/\\/g, '/');
118+
if (shouldExcludeFromBuild(newKey)) continue;
115119
updatedLatestVersions[newKey] = latestVersions[key];
116120
}
117121
for (const key in allVersions) {
118122
const newKey = key.replace(/\\/g, '/');
123+
if (shouldExcludeFromBuild(newKey)) continue;
119124
updatedAllVersions[newKey] = allVersions[key];
120125
}
121126

‎src/components/ContentBubble.js‎

Lines changed: 29 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,18 @@ const ContentBubble = ({
3737
pointer-events-none cursor-not-allowed
3838
`;
3939

40+
// In dev, allow inactive ("Coming Soon") tiles to be clickable so contributors
41+
// can preview docs they're working on without flipping the active flag. In
42+
// prod, the tile remains a non-clickable visual placeholder. Webpack injects
43+
// process.env.NODE_ENV at build time: 'development' for `npm start`,
44+
// 'production' for `npm run build`.
45+
const isDevPreviewable = !active && process.env.NODE_ENV === 'development' && (doc_location || downloadUrl);
46+
const inactiveDevClasses = `
47+
coming-soon-gradient-card
48+
hover:scale-[1.02]
49+
cursor-pointer
50+
`;
51+
4052
// Build <ThemedImage /> sources, with fallback to legacy `icon`
4153
const sources = iconLight || icon ? { light: iconLight ?? icon, dark: iconDark ?? iconLight ?? icon } : null;
4254

@@ -74,11 +86,23 @@ const ContentBubble = ({
7486
);
7587
}
7688

77-
return active ? (
78-
<a href={doc_location} className={`${baseClasses} ${activeClasses}`}>
79-
<Inner isDraft={draft} />
80-
</a>
81-
) : (
89+
if (active) {
90+
return (
91+
<a href={doc_location} className={`${baseClasses} ${activeClasses}`}>
92+
<Inner isDraft={draft} />
93+
</a>
94+
);
95+
}
96+
97+
if (isDevPreviewable) {
98+
return (
99+
<a href={downloadUrl ?? doc_location} className={`${baseClasses} ${inactiveDevClasses}`} {...(downloadUrl ? { download: true } : {})}>
100+
<Inner comingSoon isDraft={draft} />
101+
</a>
102+
);
103+
}
104+
105+
return (
82106
<div className={`${baseClasses} ${inactiveClasses}`}>
83107
<Inner comingSoon />
84108
</div>

0 commit comments

Comments
 (0)