[task/TOF] Move theme files into theme/, phases 0+1

.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,25 +4,26 @@
   "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",
     "_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 --",
+    "_sync:theme-deps": "node scripts/sync-theme-deps.mjs",
     "_spv:example": "echo TBC - npm run -s __spv docsy.dev/config/example/params.yaml --",
     "_spv": "npm run -s __spv docsy.dev/config/*/params.yaml --",
     "build": "npm run -C docsy.dev build --",
@@ -45,8 +46,8 @@
     "get:hugo-modules": "node scripts/getHugoModules/index.mjs",
     "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 --",
@@ -79,5 +80,5 @@
   "engines": {
     "node": ">=24"
   },
-  "spelling": "cSpell:ignore afdocs docsy hugo fortawesome fontawesome onedark -"
+  "spelling": "cSpell:ignore -"
 }

scripts/_gen-chroma-style.sh

@@ -6,7 +6,7 @@ set -eo pipefail
 
 HUGO="npx hugo"
 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

@@ -22,8 +22,8 @@ function getHugoModule(npmPkgNm, hugoModuleRefAtV) {
     }
 
     const command = `npx hugo mod get ${hugoModuleRefAtV}${pkgVers}`;
-    console.log(`> ${command}`);
-    const output = execSync(command);
+    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

@@ -118,7 +118,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 +128,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 +159,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/scrollspy-patch/README.md

@@ -8,32 +8,32 @@ method as the METHOD.
 
 - `node_modules/bootstrap/js/src/scrollspy.js`: the SOURCE_FILE containing the
   METHOD to be patched.
-- `assets/js/scrollspy-patch.js`: code that patches the METHOD at runtime
+- `theme/assets/js/scrollspy-patch.js`: code that patches the METHOD at runtime
   (RUNTIME_PATCHER_JS). Everything described here is in support of creating this
   file from the original Bootstrap SOURCE_FILE.
 
 Intermediate files used to simplify the process of creating the
 RUNTIME_PATCHER_JS file, and detecting when the METHOD code has changed:
 
-- `assets/_cache/bootstrap/scrollspy-method.js`: the METHOD function source
-  extracted from SOURCE_FILE (METHOD_SOURCE_FILE)
-- `assets/_cache/bootstrap/method.patch`: standard patch used to create our
-  patched METHOD code; it is in standard unified diff format (generated by
+- `theme/assets/_cache/bootstrap/scrollspy-method.js`: the METHOD function
+  source extracted from SOURCE_FILE (METHOD_SOURCE_FILE)
+- `theme/assets/_cache/bootstrap/method.patch`: standard patch used to create
+  our patched METHOD code; it is in standard unified diff format (generated by
   `diff -u` and applied by the standard `patch` command).
-- `assets/_cache/bootstrap/scrollspy-method-patched.js` - the METHOD function
-  patched.
+- `theme/assets/_cache/bootstrap/scrollspy-method-patched.js` - the METHOD
+  function patched.
 
 ## Scripts
 
 - `extract-method.pl` - Extracts the METHOD from SOURCE_FILE and saves it to the
   METHOD_SOURCE_FILE file.
 - `apply-patch.sh` - Applies the patch using the standard `patch` command and
   saves the patched method to `scrollspy-method-patched.js`
-- `update-patch-js.pl` - Updates `assets/js/scrollspy-patch.js` with the patched
-  method from `scrollspy-method-patched.js`
+- `update-patch-js.pl` - Updates `theme/assets/js/scrollspy-patch.js` with the
+  patched method from `scrollspy-method-patched.js`
 
-The patch file `method.patch` is stored in `assets/_cache/bootstrap/` alongside
-the cached method file.
+The patch file `method.patch` is stored in `theme/assets/_cache/bootstrap/`
+alongside the cached method file.
 
 ## Workflow
 
@@ -42,11 +42,11 @@ the cached method file.
 The `_prepare:scrollspy-patch` script (called by `_prepare`) automatically:
 
 1. Extracts the method from Bootstrap (`_cp:bs-scrollspy`) - writes to
-   `assets/_cache/bootstrap/scrollspy-method.js`
+   `theme/assets/_cache/bootstrap/scrollspy-method.js`
 2. Applies the patch (`apply-patch.sh`) - writes patched method to
-   `assets/_cache/bootstrap/scrollspy-method-patched.js`
-3. Updates `assets/js/scrollspy-patch.js` (`update-patch-js.pl`) - syncs the
-   patched method body into the runtime patch file
+   `theme/assets/_cache/bootstrap/scrollspy-method-patched.js`
+3. Updates `theme/assets/js/scrollspy-patch.js` (`update-patch-js.pl`) - syncs
+   the patched method body into the runtime patch file
 
 The `ci:prepare` script calls `_prepare` and `_diff:check` to ensure no
 unexpected changes occurred. If the cached method source, patched result, or
@@ -71,7 +71,7 @@ When the METHOD code has changed:
 - Manually regenerate the patch file by running:
 
   ```bash
-  cd assets/_cache/bootstrap &&
+  cd theme/assets/_cache/bootstrap &&
   diff -u scrollspy-method.js scrollspy-method-patched.js > method.patch
   ```
 

scripts/scrollspy-patch/apply-patch.sh

@@ -11,7 +11,7 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 
-CACHE_DIR="$PROJECT_ROOT/assets/_cache/bootstrap"
+CACHE_DIR="$PROJECT_ROOT/theme/assets/_cache/bootstrap"
 CACHED_METHOD_FILE="$CACHE_DIR/scrollspy-method.js"
 PATCH_FILE="$CACHE_DIR/method.patch"
 PATCHED_DEST_FILE="$CACHE_DIR/scrollspy-method-patched.js"

scripts/scrollspy-patch/extract-method.pl

@@ -15,7 +15,7 @@
 my $PROJECT_ROOT = dirname(dirname($SCRIPT_DIR));
 
 my $BOOTSTRAP_SOURCE = "$PROJECT_ROOT/node_modules/bootstrap/js/src/scrollspy.js";
-my $CACHED_METHOD_FILE = "$PROJECT_ROOT/assets/_cache/bootstrap/scrollspy-method.js";
+my $CACHED_METHOD_FILE = "$PROJECT_ROOT/theme/assets/_cache/bootstrap/scrollspy-method.js";
 
 # Check if Bootstrap source exists
 unless (-f $BOOTSTRAP_SOURCE) {

scripts/scrollspy-patch/update-patch-js.pl

@@ -1,7 +1,7 @@
 #!/usr/bin/env perl
 #
-# Updates assets/js/scrollspy-patch.js with the patched method from
-# assets/_cache/bootstrap/scrollspy-method-patched.js
+# Updates theme/assets/js/scrollspy-patch.js with the patched method from
+# theme/assets/_cache/bootstrap/scrollspy-method-patched.js
 #
 # cSpell:ignore scrollspy
 
@@ -13,8 +13,8 @@
 my $SCRIPT_DIR = dirname(abs_path(__FILE__));
 my $PROJECT_ROOT = dirname(dirname($SCRIPT_DIR));
 
-my $PATCHED_METHOD_FILE = "$PROJECT_ROOT/assets/_cache/bootstrap/scrollspy-method-patched.js";
-my $PATCH_JS_FILE = "$PROJECT_ROOT/assets/js/scrollspy-patch.js";
+my $PATCHED_METHOD_FILE = "$PROJECT_ROOT/theme/assets/_cache/bootstrap/scrollspy-method-patched.js";
+my $PATCH_JS_FILE = "$PROJECT_ROOT/theme/assets/js/scrollspy-patch.js";
 
 sub main {
     # Check if patched method file exists