[CI] Handle creation of empty Hugo-modules for deps (#2128)

package.json

@@ -11,7 +11,7 @@
     "_cp:bs-rfs": "npx cpy 'node_modules/bootstrap/scss/vendor/*' assets/_vendor/bootstrap/scss/",
     "_diff:check": "git diff --name-only --exit-code",
     "_gen-chroma-styles": "bash -c tools/gen-chroma-styles.sh && bash -c 'tools/gen-chroma-styles.sh -s onedark -o _dark.scss'",
-    "_mkdir:hugo-mod": "npx mkdirp ../github.com/FortAwesome/Font-Awesome ../github.com/twbs/bootstrap",
+    "_mkdir:hugo-mod": "node tools/mkdirp-hugo-mod.js ..",
     "_prepare": "npm run _cp:bs-rfs && npm run _gen-chroma-styles && npm run get:hugo-modules",
     "build:preview": "npm run cd:docs build:preview",
     "build:production": "npm run cd:docs build:production",
@@ -41,7 +41,6 @@
   "devDependencies": {
     "cpy-cli": "^5.0.0",
     "hugo-extended": "0.138.0",
-    "mkdirp": "^3.0.1",
     "prettier": "^3.3.3",
     "netlify-cli": "^17.37.2",
     "npm-check-updates": "^17.1.11"

tools/mkdirp-hugo-mod.js

@@ -0,0 +1,59 @@
+// Helper script to create empty Hugo-module directories for Docsy dependencies
+// listed in `go.mod`. This is necessary for projects not using Hugo modules. For
+// details, see
+// https://www.docsy.dev/docs/get-started/other-options/#docsy-npm-install-side-effect
+
+const fs = require('fs');
+const path = require('path');
+
+if (process.env.DOCSY_MKDIR_HUGO_MOD_SKIP) {
+  console.log("DOCSY_MKDIR_HUGO_MOD_SKIP is set. Skipping directory creation.");
+  process.exit(0);
+}
+
+const modulePathPrefix = process.argv[2] || '..';
+console.log(
+  `Creating empty directories under MODULE_PATH_PREFIX: ${modulePathPrefix}
+  which resolves to: ${path.resolve(modulePathPrefix)}\n`
+);
+
+// Extract module paths from `go.mod`, assuming the dependencies appear in the form:
+//
+// require (
+//   github.com/...
+//   ...
+// )
+function extractModulePaths() {
+  const goModPath = path.join(__dirname, '..', 'go.mod');
+
+  let directories = [];
+  try {
+    const goModContent = fs.readFileSync(goModPath, 'utf8');
+    const lines = goModContent.split('\n');
+    lines.forEach((line) => {
+      line = line.trim();
+      if (!line.startsWith('github.com')) return;
+      const modulePath = line.split(' ')[0];
+      directories.push(modulePath);
+    });
+  } catch (error) {
+    console.error(`Error reading go.mod file: ${error.message}`);
+    process.exit(1);
+  }
+  return directories;
+}
+
+function createDirectory(targetPath) {
+  if (!fs.existsSync(targetPath)) {
+    console.log(`+ Creating directory ${targetPath}`);
+    fs.mkdirSync(targetPath, { recursive: true });
+  } else {
+    console.log(`> Directory already exists: ${targetPath}`);
+  }
+}
+
+const directories = extractModulePaths();
+directories.forEach((dir) => {
+  const targetPath = path.join(modulePathPrefix, dir);
+  createDirectory(targetPath);
+});

userguide/content/en/docs/get-started/other-options.md

@@ -322,7 +322,11 @@ $ ls themes
 docsy                   github.com
 ```
 
-This is a workaround necessary to support Docsy's use as a single [Hugo module] ([#1120]).
+This is a workaround necessary to support Docsy's use as a single [Hugo module]
+([#1120]) in the context of projects _not_ using Hugo modules. The `github.com`
+folder is created via Docsy's `postinstall` script. To disable this behavior,
+set the environment variable `DOCSY_MKDIR_HUGO_MOD_SKIP=1` before running NPM
+install.
 
 [#1120]: https://github.com/google/docsy/issues/1120
 [0.8.0]: https://github.com/google/docsy/blob/main/CHANGELOG.md/#080