Modernize docs/v3: Update dependencies, add JavaScript bundler, and implement dark mode

docs/v3/Gemfile

@@ -1,14 +1,15 @@
 source 'https://rubygems.org'
 
 gem 'json', '>= 2.3.0'
-gem 'middleman', '~> 4.5'
+gem 'middleman', '~> 4.6'
 gem 'middleman-autoprefixer', '~> 3.0', '>= 3.0.0'
+gem 'autoprefixer-rails', '~> 10.4.7'
 gem 'middleman-gh-pages', '>= 0.0.3'
 gem 'middleman-livereload', '>= 3.4.7'
-gem 'middleman-sprockets', '~> 4.1', '>= 4.1.1'
-gem 'middleman-syntax', '3.6.1'
+gem 'middleman-syntax', '~> 3.6'
 gem 'mini_racer'
 gem 'nokogiri', '~> 1.19.1'
 gem 'rake', '>= 12.3.3'
 gem 'redcarpet', '~> 3.6.1'
 gem 'sass'
+gem 'webrick'

docs/v3/Gemfile.lock

@@ -1,60 +1,59 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (7.0.10)
+    activesupport (8.1.2)
       base64
-      benchmark (>= 0.3)
       bigdecimal
-      concurrent-ruby (~> 1.0, >= 1.0.2)
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
       drb
       i18n (>= 1.6, < 2)
+      json
       logger (>= 1.4.2)
       minitest (>= 5.1)
-      mutex_m
       securerandom (>= 0.3)
-      tzinfo (~> 2.0)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
     addressable (2.8.8)
       public_suffix (>= 2.0.2, < 8.0)
-    autoprefixer-rails (10.4.7.0)
+    autoprefixer-rails (10.4.21.0)
       execjs (~> 2)
-    backports (3.25.3)
     base64 (0.3.0)
-    benchmark (0.5.0)
     bigdecimal (4.0.1)
     coffee-script (2.4.1)
       coffee-script-source
       execjs
     coffee-script-source (1.12.2)
     concurrent-ruby (1.3.6)
-    contracts (0.16.1)
+    connection_pool (3.0.2)
+    contracts (0.17.3)
     dotenv (3.2.0)
     drb (2.2.3)
     em-websocket (0.5.3)
       eventmachine (>= 0.12.9)
       http_parser.rb (~> 0)
-    erubis (2.7.0)
+    erubi (1.13.1)
     eventmachine (1.2.7)
     execjs (2.10.0)
     fast_blank (1.0.1)
     fastimage (2.4.0)
-    ffi (1.17.3)
     ffi (1.17.3-arm64-darwin)
     ffi (1.17.3-x86_64-darwin)
     ffi (1.17.3-x86_64-linux-gnu)
-    haml (6.3.0)
+    haml (6.4.0)
       temple (>= 0.8.2)
       thor
       tilt
     hamster (3.0.0)
       concurrent-ruby (~> 1.0)
-    hashie (3.6.0)
-    http_parser.rb (0.8.0)
-    i18n (1.6.0)
+    hashie (5.1.0)
+      logger
+    http_parser.rb (0.8.1)
+    i18n (1.14.8)
       concurrent-ruby (~> 1.0)
-    json (2.18.0)
-    kramdown (2.4.0)
-      rexml
-    libv8-node (24.12.0.1)
+    json (2.18.1)
+    kramdown (2.5.2)
+      rexml (>= 3.4.4)
     libv8-node (24.12.0.1-arm64-darwin)
     libv8-node (24.12.0.1-x86_64-darwin)
     libv8-node (24.12.0.1-x86_64-linux)
@@ -64,88 +63,83 @@ GEM
       rb-inotify (~> 0.9, >= 0.9.10)
     logger (1.7.0)
     memoist (0.16.2)
-    middleman (4.5.1)
-      coffee-script (~> 2.2)
-      haml (>= 4.0.5)
-      kramdown (>= 2.3.0)
-      middleman-cli (= 4.5.1)
-      middleman-core (= 4.5.1)
+    middleman (4.6.3)
+      middleman-cli (= 4.6.3)
+      middleman-core (= 4.6.3)
     middleman-autoprefixer (3.0.0)
       autoprefixer-rails (~> 10.0)
       middleman-core (>= 4.0.0)
-    middleman-cli (4.5.1)
-      thor (>= 0.17.0, < 1.3.0)
-    middleman-core (4.5.1)
-      activesupport (>= 6.1, < 7.1)
+    middleman-cli (4.6.3)
+      thor (>= 0.17.0, < 2)
+    middleman-core (4.6.3)
+      activesupport (>= 6.1)
       addressable (~> 2.4)
-      backports (~> 3.6)
-      bundler (~> 2.0)
-      contracts (~> 0.13, < 0.17)
+      bundler (> 2.0)
+      coffee-script (~> 2.2)
+      contracts
       dotenv
-      erubis
+      erubi
       execjs (~> 2.0)
       fast_blank
       fastimage (~> 2.0)
+      haml (>= 4.0.5, < 7)
       hamster (~> 3.0)
-      hashie (~> 3.4)
-      i18n (~> 1.6.0)
+      hashie (>= 3.4, < 6.0)
+      i18n (>= 1.6, < 1.15)
+      kramdown (~> 2.4)
       listen (~> 3.0)
       memoist (~> 0.14)
-      padrino-helpers (~> 0.15.0)
+      padrino-helpers (>= 0.15, < 0.17)
       parallel
-      rack (>= 1.4.5, < 3)
+      rack (>= 3)
+      rackup
       sassc (~> 2.0)
       servolux
-      tilt (~> 2.0.9)
+      tilt (~> 2.2)
       toml
-      uglifier (~> 3.0)
+      uglifier (>= 3, < 5)
       webrick
     middleman-gh-pages (0.4.1)
       rake (> 0.9.3)
-    middleman-livereload (3.4.7)
+    middleman-livereload (3.5.0)
       em-websocket (~> 0.5.1)
       middleman-core (>= 3.3)
-      rack-livereload (~> 0.3.15)
-    middleman-sprockets (4.1.1)
-      middleman-core (~> 4.0)
-      sprockets (>= 3.0)
+      rack-livereload (~> 0.6.1)
     middleman-syntax (3.6.1)
       middleman-core (>= 3.2)
       rouge (~> 3.2)
-    mini_portile2 (2.8.9)
     mini_racer (0.19.2)
       libv8-node (~> 24.12.0.1)
     minitest (6.0.1)
       prism (~> 1.5)
     mutex_m (0.3.0)
-    nokogiri (1.19.1)
-      mini_portile2 (~> 2.8.2)
-      racc (~> 1.4)
     nokogiri (1.19.1-arm64-darwin)
       racc (~> 1.4)
     nokogiri (1.19.1-x86_64-darwin)
       racc (~> 1.4)
     nokogiri (1.19.1-x86_64-linux-gnu)
       racc (~> 1.4)
-    padrino-helpers (0.15.3)
+    padrino-helpers (0.16.0)
       i18n (>= 0.6.7, < 2)
-      padrino-support (= 0.15.3)
-      tilt (>= 1.4.1, < 3)
-    padrino-support (0.15.3)
+      padrino-support (= 0.16.0)
+      tilt (>= 2.1, < 3)
+    padrino-support (0.16.0)
     parallel (1.27.0)
     parslet (2.0.0)
-    prism (1.8.0)
+    prism (1.9.0)
     public_suffix (7.0.2)
     racc (1.8.1)
-    rack (2.2.22)
-    rack-livereload (0.3.17)
-      rack
+    rack (3.1.20)
+    rack-livereload (0.6.1)
+      rack (>= 3.0, < 3.2)
+    rackup (2.3.1)
+      rack (>= 3)
     rake (13.3.1)
     rb-fsevent (0.11.2)
     rb-inotify (0.11.1)
       ffi (~> 1.0)
     redcarpet (3.6.1)
-    rexml (3.4.2)
+    rexml (3.4.4)
     rouge (3.30.0)
     sass (3.7.4)
       sass-listen (~> 4.0.0)
@@ -156,39 +150,37 @@ GEM
       ffi (~> 1.9)
     securerandom (0.4.1)
     servolux (0.13.0)
-    sprockets (3.7.2)
-      concurrent-ruby (~> 1.0)
-      rack (> 1, < 3)
-    temple (0.10.3)
-    thor (1.2.2)
-    tilt (2.0.11)
+    temple (0.10.4)
+    thor (1.5.0)
+    tilt (2.7.0)
     toml (0.3.0)
       parslet (>= 1.8.0, < 3.0.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    uglifier (3.2.0)
+    uglifier (4.2.1)
       execjs (>= 0.3.0, < 3)
+    uri (1.1.1)
     webrick (1.9.2)
 
 PLATFORMS
   arm64-darwin
-  ruby
   x86_64-darwin
   x86_64-linux
 
 DEPENDENCIES
+  autoprefixer-rails (~> 10.4.7)
   json (>= 2.3.0)
-  middleman (~> 4.5)
+  middleman (~> 4.6)
   middleman-autoprefixer (~> 3.0, >= 3.0.0)
   middleman-gh-pages (>= 0.0.3)
   middleman-livereload (>= 3.4.7)
-  middleman-sprockets (~> 4.1, >= 4.1.1)
-  middleman-syntax (= 3.6.1)
+  middleman-syntax (~> 3.6)
   mini_racer
   nokogiri (~> 1.19.1)
   rake (>= 12.3.3)
   redcarpet (~> 3.6.1)
   sass
+  webrick
 
 BUNDLED WITH
-   2.4.19
+   2.6.9

docs/v3/README.md

@@ -13,6 +13,17 @@ Getting Started
 - Start the test server: `npm start`
 - You can now see the docs at <http://localhost:8000>.
 
+Working with JavaScript
+-----------------------
+
+JavaScript files are maintained as separate source files in `source/javascripts/lib/` and `source/javascripts/app/` directories, then concatenated into `source/javascripts/all.js` by a build script.
+
+- **During development**: `npm start` automatically rebuilds the JavaScript bundle before starting the server
+- **Manual rebuild**: If you modify any JavaScript files in `lib/` or `app/`, run `npm run build:js` to regenerate `all.js`
+- **DO NOT edit** `source/javascripts/all.js` directly - it's auto-generated and your changes will be overwritten
+
+The build script (`build-js.mjs`) concatenates files in the correct dependency order. If you need to add or reorder JavaScript files, edit the `files` array in `build-js.mjs`.
+
 Making New Files
 ----------------
 

docs/v3/build-js.mjs

@@ -0,0 +1,45 @@
+// JavaScript bundler for docs/v3
+
+import { readFileSync, writeFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const files = [
+  'lib/_energize.js',
+  'lib/_dropdown.js',
+  'lib/_lunr.js',
+  'app/_search.js',
+  'lib/_jquery_ui.js',
+  'lib/_jquery.tocify.js',
+  'lib/_imagesloaded.min.js',
+  'app/_toc.js',
+  'app/_version_dropdown.js',
+  'app/_theme_toggle.js'
+];
+
+const sourceDir = join(__dirname, 'source/javascripts');
+const outputFile = join(sourceDir, 'all.js');
+
+let bundleContent = `// Auto-generated JavaScript bundle
+// Generated by: npm run build:js
+// Source files are in lib/ and app/ directories
+// DO NOT edit this file directly - edit the source files and regenerate
+`;
+
+for (const file of files) {
+  const filePath = join(sourceDir, file);
+  const content = readFileSync(filePath, 'utf-8');
+  const cleanContent = content
+    .split('\n')
+    .filter(line => !line.trim().startsWith('//= require'))
+    .join('\n');
+
+  bundleContent += `// From: ${file}\n`;
+  bundleContent += cleanContent + ';\n\n';
+}
+
+writeFileSync(outputFile, bundleContent);
+console.log(`✓ JavaScript bundle created: ${outputFile}`);

docs/v3/config.rb

@@ -20,8 +20,6 @@
 # Activate the syntax highlighter
 activate :syntax
 
-activate :sprockets
-
 activate :autoprefixer do |config|
   config.browsers = ['last 2 version', 'Firefox ESR']
   config.cascade  = false

docs/v3/package.json

@@ -4,7 +4,8 @@
   "description": "Cloud Foundry API Docs ========",
   "main": "index.js",
   "scripts": {
-    "start": "./node_modules/.bin/gulp",
+    "build:js": "node build-js.mjs",
+    "start": "npm run build:js && ./node_modules/.bin/gulp",
     "test": "echo \"Error: no test specified\" && exit 1",
     "checkdocs": "./node_modules/.bin/gulp checkdocs"
   },