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,8 +39,11 @@
     "nguyen",
     "nvmrc",
     "Occitan",
+    "onedark",
     "pageinfo",
     "pexels",
+    "prereq",
+    "prereqs",
     "quang",
     "readfile",
     "refcache",

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

@@ -5,14 +5,15 @@
 
 [build]
 publish = "docsy.dev/public"
-command = "scripts/_install.sh && npm run build:preview"
+command = "npm run install:all && 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"
+command = "npm run install:all && npm run build:production"
 
 [context.doc-rooted.environment]
 TD_BUILD_CTX = "doc-rooted"

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",
@@ -23,9 +24,11 @@
     "clean": "rm -Rf public",
     "fix:format": "npm run _check:format -- --write",
     "fix": "npm run fix:format && npm run prune:refcache",
+    "install:all": "npm install -C .. && npm install",
     "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 +42,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-hugo.sh

@@ -1,6 +1,8 @@
 #!/bin/bash
 #
-# Install the hugo-extended NPM package if not already present.
+# Install the hugo-extended NPM package if not already present either from the
+# canonical source or from the chalin fork. The fork version is used when a Hugo
+# version hasn't yet landed on `hugo-extended` as an NPM package.
 
 set -e
 
@@ -14,5 +16,3 @@ if ! npm ls hugo-extended; then
     npm install --save-exact -D chalin/hugo-extended#v$_HUGO_EXTENDED_VERS --omit=optional
   fi
 fi
-
-# cSpell:ignore chalin

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,10 +57,12 @@
     "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": "node tests/smoke.test.mjs --branch main",
     "test:tooling": "node --test 'scripts/**/*.test.mjs'",
     "test:website": "npm run -C docsy.dev test",
     "test": "npm run fix-and-test",
     "update:dep": "npm install --save-exact @fortawesome/fontawesome-free@latest bootstrap@latest",
+    "update:packages:not-hugo": "npm run update:packages -- -x hugo-extended",
     "update:packages": "npx npm-check-updates -x @fortawesome/fontawesome-free -u && npm run -C docsy.dev update:packages",
     "zzz": "echo 'This is just a placeholder that is the last script in this script collection.'"
   },
@@ -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 @@ function getHugoModule(npmPkgNm, hugoModuleRefAtV) {
       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() {
@@ -177,7 +180,7 @@ function main() {
     echo "[INFO] Getting Docsy as NPM package '$NPM_PKG'"
     DEPS+=" $NPM_PKG"
   elif [[ "$DOCSY_SRC" == "LOCAL" ]]; then
-    echo "[INFO] Getting Docsy through a local directory '$THEMESDIR"
+    echo "[INFO] Getting Docsy through a local directory '$THEMESDIR'"
   fi
 
   [[ $VERBOSE ]] && set -x

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;