Ruby v3

.gitignore

@@ -23,5 +23,9 @@ _yardoc
 doc/
 .idea/
 
+/gems/
+/extensions/
+/vendor/bundle/
+
 # Vagrant artifacts
 ubuntu-*-console.log

.ruby-version

@@ -1 +1 @@
-2.7.8
+3.2.2

Gemfile.lock

@@ -8,14 +8,17 @@ GEM
       concurrent-ruby (~> 1.0, >= 1.0.2)
       connection_pool (>= 2.2.5)
       drb
-      i18n (>= 1.6, < 2)
       logger (>= 1.4.2)
-      minitest (>= 5.1)
       mutex_m
       securerandom (>= 0.3)
       tzinfo (~> 2.0)
-    addressable (2.8.7)
-      public_suffix (>= 2.0.2, < 7.0)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+    addressable (2.8.8)
+      public_suffix (>= 2.0.2, < 8.0)
+    autoprefixer-rails (9.8.6.5)
+      execjs
+    backports (3.25.2)
     autoprefixer-rails (10.4.21.0)
       execjs (~> 2)
     base64 (0.3.0)
@@ -94,7 +97,9 @@ GEM
       middleman-core (>= 3.2)
       rouge (~> 3.2)
     mini_portile2 (2.8.9)
-    minitest (5.26.1)
+    mini_racer (0.19.1)
+      libv8-node (~> 24.1.0.0)
+    minitest (5.26.2)
     mutex_m (0.3.0)
     nokogiri (1.13.10)
       mini_portile2 (~> 2.8.0)
@@ -105,8 +110,8 @@ GEM
       tilt (>= 1.4.1, < 3)
     padrino-support (0.15.3)
     parallel (1.27.0)
+    public_suffix (7.0.0)
     parslet (2.0.0)
-    public_suffix (5.1.1)
     racc (1.8.1)
     rack (3.2.4)
     rackup (2.2.1)
@@ -156,7 +161,7 @@ DEPENDENCIES
   webrick
 
 RUBY VERSION
-   ruby 2.7.8p225
+   ruby 3.2.2p53
 
 BUNDLED WITH
-   2.1.4
+   2.4.10

RUBY3_UPGRADE.md

@@ -0,0 +1,161 @@
+# Ruby 3.2.2 Upgrade Steps for Middleman Project
+
+## Summary
+This document outlines the steps taken to upgrade this Middleman project from Ruby 2.7.8 to Ruby 3.2.2 and fix CSS compilation issues.
+
+## Steps to Reproduce
+
+### 1. Upgrade Ruby Version
+```bash
+cd /Users/kurt/repos/new/api-docs
+echo "3.2.2" > .ruby-version
+```
+
+### 2. Clean Old Dependencies
+```bash
+rm -rf Gemfile.lock vendor/bundle .bundle
+```
+
+### 3. Update Gemfile
+Update the `Gemfile` with Ruby 3.2+ compatible versions:
+
+```ruby
+source 'https://rubygems.org'
+
+ruby '>=2.7.0'
+
+# Middleman - using 4.3.x for better compatibility
+gem 'middleman', '~> 4.3.0'
+gem 'middleman-syntax', '~> 3.2.0'
+gem 'middleman-autoprefixer', '~> 2.10.0'
+gem 'middleman-sprockets', '~> 4.1.0'
+gem 'rouge', '~> 3.26'
+gem 'redcarpet', '~> 3.5.0'
+gem 'nokogiri', '~> 1.13.0'
+gem 'haml', '~> 5.2'  # Pin to Haml 5.x for middleman-syntax compatibility
+
+gem 'execjs'
+gem 'mini_racer', platforms: :ruby
+
+# Standard libraries removed from Ruby 3.4+
+gem 'mutex_m'
+gem 'webrick'
+gem 'base64'
+gem 'bigdecimal'
+```
+
+### 4. Install Gems
+```bash
+bundle install
+```
+
+### 5. Fix config.rb - Remove Incompatible Renderer
+Edit `config.rb`:
+
+**Remove this line:**
+```ruby
+renderer: UniqueHeadCounter
+```
+
+**From the markdown configuration block, so it looks like:**
+```ruby
+# Markdown
+set :markdown_engine, :redcarpet
+set :markdown,
+    fenced_code_blocks: true,
+    smartypants: true,
+    disable_indented_code_blocks: true,
+    prettify: true,
+    tables: true,
+    with_toc_data: true,
+    no_intra_emphasis: true
+```
+
+### 6. Configure Sprockets to Handle JS Only (Not CSS)
+In `config.rb`, configure Sprockets to only process JavaScript files:
+
+```ruby
+# Configure Sprockets to handle JS only, not CSS
+activate :sprockets do |c|
+  c.supported_output_extensions = ['.js']
+end
+```
+
+**Why this works:**
+- Sprockets handles JavaScript bundling (needed for navigation to work)
+- Middleman's native Sass compiler handles CSS (properly inlines all `@import` statements)
+- Without this, Sprockets tries to handle CSS but doesn't inline `@import` statements, causing 404 errors
+
+### 7. Disable Autoprefixer
+In `config.rb`, comment out autoprefixer (causes CSS syntax errors with Ruby 3.2):
+
+```ruby
+# Autoprefixer disabled - causes CSS syntax errors with Ruby 3.2
+# activate :autoprefixer do |config|
+#   config.browsers = ['last 2 version', 'Firefox ESR']
+#   config.cascade  = false
+#   config.inline   = true
+# end
+```
+
+### 8. Update Sass Imports to Use Double Quotes
+In `source/stylesheets/screen.css.scss` and `source/stylesheets/print.css.scss`, change single quotes to double quotes for imports:
+
+```scss
+@charset "utf-8";
+@import "normalize";
+@import "variables";
+@import "icon-font";
+```
+
+### 9. Add Comment to _normalize.scss
+Add a comment at the top of `source/stylesheets/_normalize.scss` to force Sass to inline it:
+
+```scss
+/*! normalize.css v3.0.2 | MIT License | git.io/normalize */
+// Force Sass to inline this file instead of emitting a runtime @import
+```
+
+### 10. Run Middleman
+```bash
+bundle exec middleman server
+```
+
+## What Changed
+
+### Key Issues Fixed:
+1. **UniqueHeadCounter renderer** - Incompatible with Ruby 3.2's Redcarpet initialization
+2. **Sprockets** - Was not properly inlining Sass `@import` statements, causing 404 errors
+3. **Autoprefixer** - Causing CSS syntax errors with Ruby 3.2
+4. **Sass compilation** - Switched from Sprockets to Middleman's native Sass compiler
+
+### Why It Works Now:
+- **Native Sass compilation** (without Sprockets) properly inlines all `@import` statements
+- The CSS is fully compiled into single files (`screen.css` and `print.css`)
+- All partials (`_normalize.scss`, `_variables.scss`, `_icon-font.scss`) are expanded inline
+- Font URLs are properly resolved to `/fonts/` paths
+
+## Files Modified
+- `.ruby-version` - Changed to `3.2.2`
+- `Gemfile` - Updated gem versions for Ruby 3.2 compatibility
+- `config.rb` - Removed UniqueHeadCounter, disabled Sprockets and Autoprefixer
+- `source/stylesheets/screen.css.scss` - Changed imports to double quotes
+- `source/stylesheets/print.css.scss` - Changed imports to double quotes
+- `source/stylesheets/_normalize.scss` - Added inline comment
+- `.gitignore` - Added `/gems/`, `/extensions/`, `/vendor/bundle/`
+
+## Git Ignore
+Make sure `.gitignore` includes:
+```
+/gems/
+/extensions/
+/vendor/bundle/
+```
+
+This prevents large binary files from being committed.
+
+## Notes
+- `bin/` and `specifications/` directories are safe to commit (small text files)
+- Gems are now installed to system location (`~/.rbenv/versions/3.2.2/lib/ruby/gems/3.2.0/`)
+- Use `bundle exec middleman server` to run (not just `middleman server`)
+

bin/dotenv

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by RubyGems.
+#
+# The application 'dotenv' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'rubygems'
+
+Gem.use_gemdeps
+
+version = ">= 0.a"
+
+str = ARGV.first
+if str
+  str = str.b[/\A_(.*)_\z/, 1]
+  if str and Gem::Version.correct?(str)
+    version = str
+    ARGV.shift
+  end
+end
+
+if Gem.respond_to?(:activate_bin_path)
+load Gem.activate_bin_path('dotenv', 'dotenv', version)
+else
+gem "dotenv", version
+load Gem.bin_path("dotenv", "dotenv", version)
+end

bin/erubis

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by RubyGems.
+#
+# The application 'erubis' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'rubygems'
+
+Gem.use_gemdeps
+
+version = ">= 0.a"
+
+str = ARGV.first
+if str
+  str = str.b[/\A_(.*)_\z/, 1]
+  if str and Gem::Version.correct?(str)
+    version = str
+    ARGV.shift
+  end
+end
+
+if Gem.respond_to?(:activate_bin_path)
+load Gem.activate_bin_path('erubis', 'erubis', version)
+else
+gem "erubis", version
+load Gem.bin_path("erubis", "erubis", version)
+end

bin/haml

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by RubyGems.
+#
+# The application 'haml' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'rubygems'
+
+Gem.use_gemdeps
+
+version = ">= 0.a"
+
+str = ARGV.first
+if str
+  str = str.b[/\A_(.*)_\z/, 1]
+  if str and Gem::Version.correct?(str)
+    version = str
+    ARGV.shift
+  end
+end
+
+if Gem.respond_to?(:activate_bin_path)
+load Gem.activate_bin_path('haml', 'haml', version)
+else
+gem "haml", version
+load Gem.bin_path("haml", "haml", version)
+end

bin/kramdown

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by RubyGems.
+#
+# The application 'kramdown' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'rubygems'
+
+Gem.use_gemdeps
+
+version = ">= 0.a"
+
+str = ARGV.first
+if str
+  str = str.b[/\A_(.*)_\z/, 1]
+  if str and Gem::Version.correct?(str)
+    version = str
+    ARGV.shift
+  end
+end
+
+if Gem.respond_to?(:activate_bin_path)
+load Gem.activate_bin_path('kramdown', 'kramdown', version)
+else
+gem "kramdown", version
+load Gem.bin_path("kramdown", "kramdown", version)
+end

bin/listen

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by RubyGems.
+#
+# The application 'listen' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'rubygems'
+
+Gem.use_gemdeps
+
+version = ">= 0.a"
+
+str = ARGV.first
+if str
+  str = str.b[/\A_(.*)_\z/, 1]
+  if str and Gem::Version.correct?(str)
+    version = str
+    ARGV.shift
+  end
+end
+
+if Gem.respond_to?(:activate_bin_path)
+load Gem.activate_bin_path('listen', 'listen', version)
+else
+gem "listen", version
+load Gem.bin_path("listen", "listen", version)
+end