Repo-reorg theme-only folder (TOF) task: move theme into theme/ (phases 0–4b)

.github/workflows/smoke.yaml

@@ -41,7 +41,7 @@ jobs:
 
       - name: Setup workspace
         run: |
-          npm install
+          npm run install:all -- --omit=optional
           mkdir -p tmp && cd tmp && npm init -y
         shell: bash
 

.github/workflows/test.yaml

@@ -12,7 +12,7 @@ on:
   workflow_dispatch:
 permissions:
   contents: read
-  
+
 jobs:
   build:
     runs-on: ${{ matrix.os }}
@@ -29,7 +29,7 @@ jobs:
           cache: npm
           cache-dependency-path: package.json
 
-      - run: npm install --omit=optional
+      - run: npm run install:all -- --omit=optional
 
       - if: runner.os != 'Windows'
         run: npm run ci:test

.markdownlint-cli2.yaml

@@ -5,9 +5,9 @@ customRules:
 
 globs:
   - '!docsy.dev/**'
-  - '!layouts/**'
   - '!node_modules/**'
   - '!public/**'
+  - '!theme/layouts/**'
   - '!tmp/**'
   - 'docsy.dev/content/en/blog/**/*.md'
   - 'docsy.dev/content/en/docs/_index.md'

.prettierignore

@@ -2,14 +2,14 @@
 # gotcha is that once a _directory_ is ignored, it's content cannot be
 # unignored.
 
-# Ignore all _files_ under assets
-/assets/**/*.*
+# Ignore all _files_ under the theme's assets
+/theme/assets/**/*.*
 
 # Selectively unignore some files
-!/assets/scss/main.scss
-!/assets/scss/td/**/*
+!/theme/assets/scss/main.scss
+!/theme/assets/scss/td/**/*
 
 # These files are derived from other sources,
 # don't Prettify them:
-/assets/scss/td/_variables_forward.scss
-/assets/scss/td/chroma/**/*
+/theme/assets/scss/td/_variables_forward.scss
+/theme/assets/scss/td/chroma/**/*

.vscode/cspell.json

@@ -20,6 +20,8 @@
     "docsy",
     "Docsy",
     "errorf",
+    "fontawesome",
+    "fortawesome",
     "Gantt",
     "getenv",
     "GLFM",
@@ -37,6 +39,7 @@
     "nguyen",
     "nvmrc",
     "Occitan",
+    "onedark",
     "pageinfo",
     "pexels",
     "quang",

docsy.dev/config/_default/hugo.yaml

@@ -2,7 +2,7 @@
 #
 # baseURL moved to be after params
 title: Docsy
-theme: [docsy]
+theme: [docsy/theme]
 enableRobotsTXT: true
 enableGitInfo: true
 enableEmoji: true

docsy.dev/netlify.toml

@@ -9,7 +9,8 @@ command = "scripts/_install.sh && npm run build:preview"
 
 [build.environment]
 GO_VERSION = "1.25.5"
-HUGO_THEME = "repo"
+# Netlify clones into a dir named "repo"; the theme lives in repo's theme/ subdir.
+HUGO_THEME = "repo/theme"
 
 [context.production]
 command = "scripts/_install.sh && npm run build:production"

docsy.dev/package.json

@@ -13,6 +13,7 @@
     "_hugo-dev": "cross-env npm run _hugo -- -e \"${TD_BUILD_CTX:-dev}\" -DFE --printPathWarnings",
     "_hugo": "hugo --cleanDestinationDir --logLevel info --themesDir ../..",
     "_postbuild": "npm run _check:links--warn",
+    "_install-theme-deps": "npm install ../theme --install-links --no-save && rm -rf node_modules/theme",
     "_serve": "npm run _hugo-dev -- serve --disableFastRender --renderToMemory",
     "build:preview": "cross-env npm run _hugo-dev -- --minify --baseURL \"${DEPLOY_PRIME_URL:-http://localhost}\"",
     "build:production": "npm run _hugo -- --minify",
@@ -26,6 +27,7 @@
     "make:public": "git init -b main public",
     "postbuild:preview": "npm run _postbuild",
     "postbuild:production": "npm run _postbuild",
+    "postinstall": "npm run _install-theme-deps",
     "precheck:links:all": "npm run build",
     "precheck:links": "npm run build",
     "prepare-disabled": "cd .. && npm install",
@@ -39,6 +41,7 @@
     "update:md-goldens": "node tests/md-output/update-goldens.mjs",
     "update:packages": "npx npm-check-updates -u"
   },
+  "dependencies-note": "Dependencies installed from ../theme; see postinstall script",
   "devDependencies": {
     "afdocs": "^0.9.2",
     "autoprefixer": "^10.4.27",

docsy.dev/scripts/_install.sh

@@ -3,9 +3,11 @@
 # Private script used by CI/CD workflows to install NPM packages necessary for
 # the website and theme.
 #
-# Since docsy.dev is a workspace of the Docsy repo root, we only need to install
-# the Docsy repo root dependencies. That will automatically install the
-# dependencies for docsy.dev.
+# Installs the Docsy repo-root packages (theme runtime deps + maintainer
+# tooling) and then the docsy.dev packages (site-build tooling such as
+# hugo-extended, autoprefixer, cross-env, …). The repo root currently has no
+# `docsy.dev` workspace declared, so the two installs must be invoked
+# explicitly.
 
 set -euo pipefail
 
@@ -29,7 +31,10 @@ if [ ! -f package.json ] || [ ! -d docsy.dev ]; then
     exit 1
 fi
 
-echo "Installing NPM packages for Docsy website and theme..."
-exec npm install
+echo "Installing NPM packages for the Docsy repo root..."
+npm install
+
+echo "Installing NPM packages for the docsy.dev website..."
+exec npm install -C docsy.dev
 
 # cSpell:ignore docsy

package.json

@@ -4,27 +4,28 @@
   "repository": "github:google/docsy",
   "homepage": "https://www.docsy.dev",
   "license": "Apache-2.0",
+  "workspaces-todo": "TODO: try adding theme later once all phases of repo reorg are complete",
   "workspaces": [
-    "docsy.dev"
   ],
   "scripts": {
     "__spv": "node scripts/set-package-version/index.mjs",
     "_check:afdocs": "npm run -s -C docsy.dev _check:afdocs",
-    "_check:format": "npx prettier --check assets *.md i18n scripts tasks",
+    "_check:format": "npx prettier --check theme/assets *.md theme/i18n scripts tasks tests",
     "_check:links": "npm run -C docsy.dev _check:links",
     "_check:markdown": "npx markdownlint-cli2",
     "_commit:public": "npm run -C docsy.dev _commit:public",
-    "_cp:bs-rfs": "bash -c 'cp node_modules/bootstrap/scss/vendor/*.scss assets/_vendor/bootstrap/scss/'",
+    "_cp:bs-rfs": "bash -c 'cp node_modules/bootstrap/scss/vendor/*.scss theme/assets/_vendor/bootstrap/scss/'",
     "_cp:bs-scrollspy": "perl scripts/scrollspy-patch/extract-method.pl",
     "_diff:check": "git diff --name-only --exit-code",
     "_gen-chroma-styles": "bash -c scripts/gen-chroma-styles.sh",
     "_mkdir:hugo-mod": "node scripts/mkdirp-hugo-mod.js ..",
     "_prepare:scrollspy-patch": "npm run _cp:bs-scrollspy && bash scripts/scrollspy-patch/apply-patch.sh && perl scripts/scrollspy-patch/update-patch-js.pl",
-    "_prepare": "npm run _cp:bs-rfs && npm run _prepare:scrollspy-patch && npm run _refresh-forward-sass-var && npm run _gen-chroma-styles && npm run get:hugo-modules",
+    "_prepare": "npm run _sync:theme-deps && npm run _cp:bs-rfs && npm run _prepare:scrollspy-patch && npm run _refresh-forward-sass-var && npm run _gen-chroma-styles && npm run get:hugo-modules",
     "_refresh-forward-sass-var": "bash -c scripts/refresh-sass-variables.pl",
     "_serve": "npm run -C docsy.dev _serve --",
     "_spv:example": "echo TBC - npm run -s __spv docsy.dev/config/example/params.yaml --",
     "_spv": "npm run -s __spv docsy.dev/config/*/params.yaml --",
+    "_sync:theme-deps": "node scripts/sync-theme-deps.mjs",
     "build": "npm run -C docsy.dev build --",
     "check:afdocs:dev": "npm run -s _check:afdocs -- http://localhost:1313 | tee docsy.dev/content/en/docs/content/agent-support/afdocs-scorecard.txt",
     "check:format": "npm list prettier && npm run _check:format || (echo '[help] Run: npm run fix:format'; exit 1)",
@@ -43,10 +44,11 @@
     "fix:markdown": "npm run check:markdown -- --fix",
     "fix": "npm run fix:format && npm run fix:markdown && npm run -C docsy.dev fix",
     "get:hugo-modules": "node scripts/getHugoModules/index.mjs",
+    "install:all": "npm run docsy.dev-install && npm install",
     "post-update": "echo; echo 'IMPORTANT! Run the following in case the ScrollSpy patch needs to be updated:\n  npm run _prepare'; echo",
     "postinstall": "npm run _mkdir:hugo-mod",
-    "postupdate:dep": "npm run -s post-update",
-    "postupdate:packages": "npm run -s post-update",
+    "postupdate:dep": "npm run _sync:theme-deps && npm run -s post-update",
+    "postupdate:packages": "npm run _sync:theme-deps && npm run -s post-update",
     "prune:refcache": "npm run -C docsy.dev prune:refcache --",
     "seq": "bash -c 'for cmd in \"$@\"; do npm run $cmd || exit 1; done' - ",
     "serve": "npm run -C docsy.dev serve --",
@@ -55,6 +57,8 @@
     "set:version:example": "cd ../docsy-example && node ../docsy/scripts/set-package-version/index.mjs",
     "set:version:git-info": "npm run -s _spv -- --version \"$(scripts/get-build-id.sh)\"",
     "set:version": "npm run -s _spv --",
+    "test:smoke-note": "echo 'FIXME: test:smoke pins --branch task/repo-reorg-2026-05 during the TOF rollout; remove that flag once the move merges to main (issue #2617).'",
+    "test:smoke": "node tests/smoke.test.mjs --branch task/repo-reorg-2026-05",
     "test:tooling": "node --test 'scripts/**/*.test.mjs'",
     "test:website": "npm run -C docsy.dev test",
     "test": "npm run fix-and-test",
@@ -79,5 +83,5 @@
   "engines": {
     "node": ">=24"
   },
-  "spelling": "cSpell:ignore afdocs docsy hugo fortawesome fontawesome onedark -"
+  "spelling": "cSpell:ignore -"
 }

scripts/_gen-chroma-style.sh

@@ -4,9 +4,10 @@
 
 set -eo pipefail
 
-HUGO="npx hugo"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HUGO="node $SCRIPT_DIR/run-hugo.mjs"
 CHROMA_STYLE=
-DEST_DIR=assets/scss/td/chroma
+DEST_DIR=theme/assets/scss/td/chroma
 DEST_FILE=
 DEST_PATH=/dev/null # Set in process_CLI_args
 

scripts/getHugoModules/index.mjs

@@ -2,12 +2,15 @@
 // It gets dependency versions from `package.json`.
 
 import fs from 'fs';
+import path from 'path';
 import { execSync } from 'child_process';
 
+const SCRIPT_DIR = path.join(process.cwd(), 'scripts');
 const packageJson = readPackageJson();
 let exitStatus = 0;
 
 const exit = () => process.exit(exitStatus);
+const hugoCmd = () => `node ${SCRIPT_DIR}/run-hugo.mjs`;
 
 function getHugoModule(npmPkgNm, hugoModuleRefAtV) {
   try {
@@ -21,9 +24,9 @@
       throw new Error(msg);
     }
 
-    const command = `npx hugo mod get ${hugoModuleRefAtV}${pkgVers}`;
-    console.log(`> ${command}`);
-    const output = execSync(command);
+    const command = `${hugoCmd()} mod get ${hugoModuleRefAtV}${pkgVers}`;
+    console.log(`> (cd theme && ${command})`);
+    const output = execSync(command, { cwd: 'theme' });
     console.log(output.toString());
   } catch (error) {
     console.error(`ERROR: ${error.message}\n`);

scripts/make-site.sh

@@ -2,13 +2,15 @@
 # cSpell:ignore autoprefixer docsy postcss themesdir github oneline
 set -eo pipefail
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
 DEPS="autoprefixer postcss-cli"
 DOCSY_REPO_DEFAULT="google/docsy"
 DOCSY_REPO=$DOCSY_REPO_DEFAULT
 DOCSY_VERS=""
 DOCSY_SRC="NPM"
 FORCE_DELETE=false
-: ${HUGO:=npx hugo}
+: "${HUGO:=node $SCRIPT_DIR/run-hugo.mjs}"
 SITE_NAME="test-site"
 THEMESDIR="node_modules"
 VERBOSE=1
@@ -118,7 +120,7 @@ function set_up_and_cd_into_site() {
   if [[ "$DOCSY_SRC" == HUGO* ]]; then
     _set_up_site_using_hugo_modules
   else
-    echo "theme: docsy" >> hugo.yaml
+    echo "theme: docsy/theme" >> hugo.yaml
     echo "themesDir: $THEMESDIR" >> hugo.yaml
   fi
 }
@@ -128,7 +130,8 @@ function _set_up_site_using_hugo_modules() {
   # : ${user_name:=$USER}
   # : ${user_name:="me"}
 
-  HUGO_MOD_WITH_VERS=$DOCSY_REPO
+  # TOF: Docsy theme lives in the `theme/` subfolder of the Docsy repo.
+  HUGO_MOD_WITH_VERS="$DOCSY_REPO/theme"
   if [[ -n $DOCSY_VERS ]]; then
     HUGO_MOD_WITH_VERS+="@$DOCSY_VERS"
   fi
@@ -158,11 +161,11 @@ function _set_up_site_using_hugo_modules() {
       git log --oneline -$DEPTH && \
       if [[ -n $SWITCH_NEEDED ]]; then git switch --detach $DOCSY_VERS; fi \
     )
-    echo "replace github.com/$DOCSY_REPO_DEFAULT => ./tmp/docsy" >> go.mod
-    eval "$HUGO mod get github.com/$DOCSY_REPO_DEFAULT" $OUTPUT_REDIRECT
+    echo "replace github.com/$DOCSY_REPO_DEFAULT/theme => ./tmp/docsy/theme" >> go.mod
+    eval "$HUGO mod get github.com/$DOCSY_REPO_DEFAULT/theme" $OUTPUT_REDIRECT
   fi
 
-  echo "module: {proxy: direct, hugoVersion: {extended: true}, imports: [{path: github.com/$DOCSY_REPO_DEFAULT, disable: false}]}" >> hugo.yaml
+  echo "module: {proxy: direct, hugoVersion: {extended: true}, imports: [{path: github.com/$DOCSY_REPO_DEFAULT/theme, disable: false}]}" >> hugo.yaml
 }
 
 function main() {

scripts/mkdirp-hugo-mod.js

@@ -24,7 +24,9 @@ console.log(
 //   ...
 // )
 function extractModulePaths() {
-  const goModPath = path.join(__dirname, '..', 'go.mod');
+  // go.mod lives in theme/ as of the TOF refactor; this script remains at the
+  // repo root's scripts/ so its callers (root postinstall) need no path change.
+  const goModPath = path.join(__dirname, '..', 'theme', 'go.mod');
 
   let directories = [];
   try {

scripts/refresh-sass-variables.pl

@@ -4,7 +4,7 @@
 use warnings;
 
 my $bootstrap_vars = "node_modules/bootstrap/scss/_variables.scss";
-my $forward_vars = "assets/scss/td/_variables_forward.scss";
+my $forward_vars = "theme/assets/scss/td/_variables_forward.scss";
 die "File not found: $bootstrap_vars\n" unless -f $bootstrap_vars;
 die "File not found: $forward_vars\n" unless -f $forward_vars;
 

scripts/run-hugo.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// Resolve the installed `hugo-extended` and exec it with the forwarded args.
+// Reuses docsy.dev's install (the repo's single hugo-extended declaration,
+// version-pinned via package.json `config.hugo_version`) rather than `npx hugo`.
+// Cross-OS: runs the package's Node bin wrapper, not a POSIX symlink / Win shim.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const repoRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+);
+const searchBases = [path.join(repoRoot, 'docsy.dev'), repoRoot];
+
+function resolveHugoBin() {
+  for (const base of searchBases) {
+    // By node_modules path, not require.resolve('hugo-extended/package.json'):
+    // the package's `exports` blocks that (ERR_PACKAGE_PATH_NOT_EXPORTED).
+    const pkgDir = path.join(base, 'node_modules', 'hugo-extended');
+    const pkgJson = path.join(pkgDir, 'package.json');
+    if (!existsSync(pkgJson)) continue;
+    const { bin } = JSON.parse(readFileSync(pkgJson, 'utf8'));
+    const rel = typeof bin === 'string' ? bin : bin?.hugo;
+    if (rel) return path.join(pkgDir, rel);
+  }
+  return null;
+}
+
+const hugoBin = resolveHugoBin();
+if (!hugoBin) {
+  console.error(
+    '[run-hugo] hugo-extended not found — run `npm run install:all` first.',
+  );
+  process.exit(127);
+}
+
+const { status, error } = spawnSync(
+  process.execPath,
+  [hugoBin, ...process.argv.slice(2)],
+  { stdio: 'inherit' },
+);
+if (error) {
+  console.error(`[run-hugo] ${error.message}`);
+  process.exit(1);
+}
+process.exit(status ?? 1);