From dce3cf8542cb90db91e5032373f0dbe6e6c8fb9d Mon Sep 17 00:00:00 2001
From: Stan Lo <stan001212@gmail.com>
Date: Sun, 4 Jan 2026 16:22:28 +0000
Subject: [PATCH 1/2] Refactor code highlighting to use neutral color palette

Replace language-specific CSS variables (--c-*) with a shared neutral
color palette (--code-*) that can be reused across different syntax
highlighters. This reduces duplication and makes it easier to maintain
consistent colors across C, Ruby, and future language highlighters.

Changes:
- Add --code-cyan and --code-gray to neutral palette
- Remove --c-* semantic variables for C highlighting
- Update .c-* classes to reference neutral --code-* variables
---
 .../generator/template/aliki/css/rdoc.css     | 52 ++++++-------------
 1 file changed, 16 insertions(+), 36 deletions(-)

diff --git a/lib/rdoc/generator/template/aliki/css/rdoc.css b/lib/rdoc/generator/template/aliki/css/rdoc.css
index b99f663147..ac43caa4bb 100644
--- a/lib/rdoc/generator/template/aliki/css/rdoc.css
+++ b/lib/rdoc/generator/template/aliki/css/rdoc.css
@@ -39,24 +39,14 @@
   --color-neutral-800: #292524;
   --color-neutral-900: #1c1917;
 
-  /* Code highlighting colors */
+  /* Code highlighting colors - neutral palette for all syntax highlighters */
   --code-blue: #1d4ed8;
   --code-green: #047857;
   --code-orange: #d97706;
   --code-purple: #7e22ce;
   --code-red: #dc2626;
-
-  /* C syntax highlighting */
-  --c-keyword: #b91c1c;
-  --c-type: #0891b2;
-  --c-macro: #ea580c;
-  --c-function: #7c3aed;
-  --c-identifier: #475569;
-  --c-operator: #059669;
-  --c-preprocessor: #a21caf;
-  --c-value: #92400e;
-  --c-string: #15803d;
-  --c-comment: #78716c;
+  --code-cyan: #0891b2;
+  --code-gray: #78716c;
 
   /* Color Palette - Green (for success states) */
   --color-green-400: #4ade80;
@@ -186,24 +176,14 @@
 
 /* Dark Theme */
 [data-theme="dark"] {
-  /* Code highlighting colors */
+  /* Code highlighting colors - neutral palette for all syntax highlighters */
   --code-blue: #93c5fd;
   --code-green: #34d399;
   --code-orange: #fbbf24;
   --code-purple: #c084fc;
   --code-red: #f87171;
-
-  /* C syntax highlighting */
-  --c-keyword: #f87171;
-  --c-type: #22d3ee;
-  --c-macro: #fb923c;
-  --c-function: #a78bfa;
-  --c-identifier: #94a3b8;
-  --c-operator: #6ee7b7;
-  --c-preprocessor: #e879f9;
-  --c-value: #fcd34d;
-  --c-string: #4ade80;
-  --c-comment: #a8a29e;
+  --code-cyan: #22d3ee;
+  --code-gray: #a8a29e;
 
   /* Semantic Colors - Dark Theme */
   --color-text-primary: var(--color-neutral-50);
@@ -1064,18 +1044,18 @@ main h6 a:hover {
 [data-theme="dark"] .ruby-string     { color: var(--code-green); }
 
 /* C Syntax Highlighting */
-.c-keyword { color: var(--c-keyword); }
-.c-type { color: var(--c-type); }
-.c-macro { color: var(--c-macro); }
-.c-function { color: var(--c-function); }
-.c-identifier { color: var(--c-identifier); }
-.c-operator { color: var(--c-operator); }
-.c-preprocessor { color: var(--c-preprocessor); }
-.c-value { color: var(--c-value); }
-.c-string { color: var(--c-string); }
+.c-keyword { color: var(--code-red); }
+.c-type { color: var(--code-cyan); }
+.c-macro { color: var(--code-orange); }
+.c-function { color: var(--code-purple); }
+.c-identifier { color: var(--color-text-secondary); }
+.c-operator { color: var(--code-green); }
+.c-preprocessor { color: var(--code-purple); }
+.c-value { color: var(--code-orange); }
+.c-string { color: var(--code-green); }
 
 .c-comment {
-  color: var(--c-comment);
+  color: var(--code-gray);
   font-style: italic;
 }
 

From d92001479e6f2d02cd4dc4ecdb560ba204f56bee Mon Sep 17 00:00:00 2001
From: Stan Lo <stan001212@gmail.com>
Date: Sun, 4 Jan 2026 16:24:31 +0000
Subject: [PATCH 2/2] Add client-side shell syntax highlighter for Aliki theme

Add a simple shell/bash syntax highlighter for documentation code blocks.
The highlighter is focused on command-line documentation rather than full
bash scripts.

Highlights:
- $ prompts (gray)
- Commands/executables - first word on line (blue)
- Options like -f, --flag, --option=value (cyan)
- Single and double quoted strings (green)
- Comments starting with # (gray, italic)

The highlighter targets code blocks with language classes: bash, sh, shell,
console.

Files added:
- lib/rdoc/generator/template/aliki/js/bash_highlighter.js
- test/rdoc/generator/aliki/highlight_bash_test.rb
---
 lib/rdoc/generator/template/aliki/_head.rhtml |   5 +
 .../generator/template/aliki/css/rdoc.css     |  12 ++
 .../template/aliki/js/bash_highlighter.js     | 167 ++++++++++++++++
 .../generator/aliki/highlight_bash_test.rb    | 181 ++++++++++++++++++
 4 files changed, 365 insertions(+)
 create mode 100644 lib/rdoc/generator/template/aliki/js/bash_highlighter.js
 create mode 100644 test/rdoc/generator/aliki/highlight_bash_test.rb

diff --git a/lib/rdoc/generator/template/aliki/_head.rhtml b/lib/rdoc/generator/template/aliki/_head.rhtml
index 1733bd0174..c46f0b94e7 100644
--- a/lib/rdoc/generator/template/aliki/_head.rhtml
+++ b/lib/rdoc/generator/template/aliki/_head.rhtml
@@ -140,6 +140,11 @@
   defer
 ></script>
 
+<script
+  src="<%= h asset_rel_prefix %>/js/bash_highlighter.js?v=<%= h RDoc::VERSION %>"
+  defer
+></script>
+
 <script
   src="<%= h asset_rel_prefix %>/js/aliki.js?v=<%= h RDoc::VERSION %>"
   defer
diff --git a/lib/rdoc/generator/template/aliki/css/rdoc.css b/lib/rdoc/generator/template/aliki/css/rdoc.css
index ac43caa4bb..25a3f43076 100644
--- a/lib/rdoc/generator/template/aliki/css/rdoc.css
+++ b/lib/rdoc/generator/template/aliki/css/rdoc.css
@@ -1059,6 +1059,18 @@ main h6 a:hover {
   font-style: italic;
 }
 
+/* Shell Syntax Highlighting */
+.sh-prompt { color: var(--code-gray); }
+.sh-command { color: var(--code-blue); }
+.sh-option { color: var(--code-cyan); }
+.sh-string { color: var(--code-green); }
+.sh-envvar { color: var(--code-purple); }
+
+.sh-comment {
+  color: var(--code-gray);
+  font-style: italic;
+}
+
 /* Emphasis */
 em {
   text-decoration-color: var(--color-emphasis-decoration);
diff --git a/lib/rdoc/generator/template/aliki/js/bash_highlighter.js b/lib/rdoc/generator/template/aliki/js/bash_highlighter.js
new file mode 100644
index 0000000000..027adf2e5a
--- /dev/null
+++ b/lib/rdoc/generator/template/aliki/js/bash_highlighter.js
@@ -0,0 +1,167 @@
+/**
+ * Client-side shell syntax highlighter for RDoc
+ * Highlights: $ prompts, commands, options, strings, env vars, comments
+ */
+
+(function() {
+  'use strict';
+
+  function escapeHtml(text) {
+    return text
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#39;');
+  }
+
+  function wrap(className, text) {
+    return '<span class="' + className + '">' + escapeHtml(text) + '</span>';
+  }
+
+  function highlightLine(line) {
+    if (line.trim() === '') return escapeHtml(line);
+
+    var result = '';
+    var i = 0;
+    var len = line.length;
+
+    // Preserve leading whitespace
+    while (i < len && (line[i] === ' ' || line[i] === '\t')) {
+      result += escapeHtml(line[i++]);
+    }
+
+    // Check for $ prompt ($ followed by space or end of line)
+    if (line[i] === '$' && (line[i + 1] === ' ' || line[i + 1] === undefined)) {
+      result += wrap('sh-prompt', '$');
+      i++;
+    }
+
+    // Check for # comment at start
+    if (line[i] === '#') {
+      return result + wrap('sh-comment', line.slice(i));
+    }
+
+    var seenCommand = false;
+    var afterSpace = true;
+
+    while (i < len) {
+      var ch = line[i];
+
+      // Whitespace
+      if (ch === ' ' || ch === '\t') {
+        result += escapeHtml(ch);
+        i++;
+        afterSpace = true;
+        continue;
+      }
+
+      // Comment after whitespace
+      if (ch === '#' && afterSpace) {
+        result += wrap('sh-comment', line.slice(i));
+        break;
+      }
+
+      // Double-quoted string
+      if (ch === '"') {
+        var end = i + 1;
+        while (end < len && line[end] !== '"') {
+          if (line[end] === '\\' && end + 1 < len) end += 2;
+          else end++;
+        }
+        if (end < len) end++;
+        result += wrap('sh-string', line.slice(i, end));
+        i = end;
+        afterSpace = false;
+        continue;
+      }
+
+      // Single-quoted string
+      if (ch === "'") {
+        var end = i + 1;
+        while (end < len && line[end] !== "'") end++;
+        if (end < len) end++;
+        result += wrap('sh-string', line.slice(i, end));
+        i = end;
+        afterSpace = false;
+        continue;
+      }
+
+      // Environment variable (ALLCAPS=)
+      if (afterSpace && /[A-Z]/.test(ch)) {
+        var match = line.slice(i).match(/^[A-Z][A-Z0-9_]*=/);
+        if (match) {
+          result += wrap('sh-envvar', match[0]);
+          i += match[0].length;
+          // Read unquoted value
+          var valEnd = i;
+          while (valEnd < len && line[valEnd] !== ' ' && line[valEnd] !== '\t' && line[valEnd] !== '"' && line[valEnd] !== "'") valEnd++;
+          if (valEnd > i) {
+            result += escapeHtml(line.slice(i, valEnd));
+            i = valEnd;
+          }
+          afterSpace = false;
+          continue;
+        }
+      }
+
+      // Option (must be after whitespace)
+      if (ch === '-' && afterSpace) {
+        var match = line.slice(i).match(/^--?[a-zA-Z0-9_-]+(=[^\s]*)?/);
+        if (match) {
+          result += wrap('sh-option', match[0]);
+          i += match[0].length;
+          afterSpace = false;
+          continue;
+        }
+      }
+
+      // Command (first word: regular, ./path, ../path, ~/path, @scope/pkg)
+      if (!seenCommand && afterSpace) {
+        var isCmd = /[a-zA-Z0-9@~]/.test(ch) ||
+                    (ch === '.' && (line[i + 1] === '/' || (line[i + 1] === '.' && line[i + 2] === '/')));
+        if (isCmd) {
+          var end = i;
+          while (end < len && line[end] !== ' ' && line[end] !== '\t') end++;
+          result += wrap('sh-command', line.slice(i, end));
+          i = end;
+          seenCommand = true;
+          afterSpace = false;
+          continue;
+        }
+      }
+
+      // Everything else
+      result += escapeHtml(ch);
+      i++;
+      afterSpace = false;
+    }
+
+    return result;
+  }
+
+  function highlightShell(code) {
+    return code.split('\n').map(highlightLine).join('\n');
+  }
+
+  function initHighlighting() {
+    var selectors = [
+      'pre.bash', 'pre.sh', 'pre.shell', 'pre.console',
+      'pre[data-language="bash"]', 'pre[data-language="sh"]',
+      'pre[data-language="shell"]', 'pre[data-language="console"]'
+    ];
+
+    var blocks = document.querySelectorAll(selectors.join(', '));
+    blocks.forEach(function(block) {
+      if (block.getAttribute('data-highlighted') === 'true') return;
+      block.innerHTML = highlightShell(block.textContent);
+      block.setAttribute('data-highlighted', 'true');
+    });
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', initHighlighting);
+  } else {
+    initHighlighting();
+  }
+})();
diff --git a/test/rdoc/generator/aliki/highlight_bash_test.rb b/test/rdoc/generator/aliki/highlight_bash_test.rb
new file mode 100644
index 0000000000..103dce350d
--- /dev/null
+++ b/test/rdoc/generator/aliki/highlight_bash_test.rb
@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require_relative '../../helper'
+
+return if RUBY_DESCRIPTION =~ /truffleruby/ || RUBY_DESCRIPTION =~ /jruby/
+
+begin
+  require 'mini_racer'
+rescue LoadError
+  return
+end
+
+class RDocGeneratorAlikiHighlightBashTest < Test::Unit::TestCase
+  HIGHLIGHT_BASH_JS_PATH = File.expand_path(
+    '../../../../lib/rdoc/generator/template/aliki/js/bash_highlighter.js',
+    __dir__
+  )
+
+  HIGHLIGHT_BASH_JS = begin
+    highlight_bash_js = File.read(HIGHLIGHT_BASH_JS_PATH)
+
+    # We need to modify the JS slightly to make it work in the context of a test.
+    highlight_bash_js.gsub(
+      /\(function\(\) \{[\s\S]*'use strict';/,
+      "// Test wrapper\n"
+    ).gsub(
+      /if \(document\.readyState[\s\S]*\}\)\(\);/,
+      "// Removed DOM initialization for testing"
+    )
+  end.freeze
+
+  def setup
+    @context = MiniRacer::Context.new
+    @context.eval(HIGHLIGHT_BASH_JS)
+  end
+
+  def teardown
+    @context.dispose
+  end
+
+  def test_prompts
+    # $ followed by space or end of line is a prompt
+    [
+      ['$ bundle exec rake', '<span class="sh-prompt">$</span>'],
+      ['  $ npm install', '<span class="sh-prompt">$</span>'],
+      ['$', '<span class="sh-prompt">$</span>'],
+    ].each do |input, expected|
+      assert_includes highlight(input), expected, "Failed for: #{input}"
+    end
+
+    # $VAR is a variable, not a prompt
+    refute_includes highlight('$HOME/bin'), '<span class="sh-prompt">'
+  end
+
+  def test_comments
+    [
+      ['# This is a comment', '<span class="sh-comment"># This is a comment</span>'],
+      ['bundle exec rake # Run tests', '<span class="sh-comment"># Run tests</span>'],
+    ].each do |input, expected|
+      assert_includes highlight(input), expected, "Failed for: #{input}"
+    end
+  end
+
+  def test_options
+    [
+      ['ls -l', '<span class="sh-option">-l</span>'],
+      ['npm install --save-dev', '<span class="sh-option">--save-dev</span>'],
+      ['git commit --message=fix', '<span class="sh-option">--message=fix</span>'],
+      ['ls -la --color=auto', ['<span class="sh-option">-la</span>', '<span class="sh-option">--color=auto</span>']],
+    ].each do |input, expected|
+      Array(expected).each do |exp|
+        assert_includes highlight(input), exp, "Failed for: #{input}"
+      end
+    end
+  end
+
+  def test_strings
+    [
+      ['echo "hello world"', '<span class="sh-string">&quot;hello world&quot;</span>'],
+      ["echo 'hello world'", "<span class=\"sh-string\">&#39;hello world&#39;</span>"],
+      ['echo "hello \"world\""', '<span class="sh-string">&quot;hello \&quot;world\&quot;&quot;</span>'],
+      ['npx @herb-tools/linter "**/*.rhtml"', '<span class="sh-string">&quot;**/*.rhtml&quot;</span>'],
+    ].each do |input, expected|
+      assert_includes highlight(input), expected, "Failed for: #{input}"
+    end
+  end
+
+  def test_commands
+    result = highlight('bundle exec rake')
+    assert_includes result, '<span class="sh-command">bundle</span>'
+    # Only the first word is highlighted as command
+    refute_includes result, '<span class="sh-command">exec</span>'
+    refute_includes result, '<span class="sh-command">rake</span>'
+  end
+
+  def test_path_commands
+    [
+      ['./configure --prefix=/usr/local', '<span class="sh-command">./configure</span>'],
+      ['../configure --enable-gcov', '<span class="sh-command">../configure</span>'],
+      ['./autogen.sh', '<span class="sh-command">./autogen.sh</span>'],
+      ['~/.rubies/ruby-master/bin/ruby -e "puts 1"', '<span class="sh-command">~/.rubies/ruby-master/bin/ruby</span>'],
+    ].each do |input, expected|
+      assert_includes highlight(input), expected, "Failed for: #{input}"
+    end
+  end
+
+  def test_environment_variables
+    [
+      ['COVERAGE=true make test', ['<span class="sh-envvar">COVERAGE=</span>', '<span class="sh-command">make</span>']],
+      ['CC=clang CXX=clang++ make', ['<span class="sh-envvar">CC=</span>', '<span class="sh-envvar">CXX=</span>', '<span class="sh-command">make</span>']],
+      ['RUBY_TEST_TIMEOUT_SCALE=5 make check', ['<span class="sh-envvar">RUBY_TEST_TIMEOUT_SCALE=</span>', '<span class="sh-command">make</span>']],
+    ].each do |input, expected|
+      Array(expected).each do |exp|
+        assert_includes highlight(input), exp, "Failed for: #{input}"
+      end
+    end
+  end
+
+  def test_hyphens_in_words_not_options
+    # Hyphen in @herb-tools/linter should NOT be treated as option
+    result = highlight('npx @herb-tools/linter')
+    assert_includes result, '<span class="sh-command">npx</span>'
+    refute_includes result, '<span class="sh-option">-tools/linter</span>'
+    assert_includes result, '@herb-tools/linter'
+
+    # Command with hyphen gets highlighted as command, not option
+    result = highlight('some-command arg')
+    assert_includes result, '<span class="sh-command">some-command</span>'
+    refute_includes result, '<span class="sh-option">'
+  end
+
+  def test_complex_commands
+    # Typical shell command with prompt
+    result = highlight('$ bundle exec rubocop -A')
+    assert_includes result, '<span class="sh-prompt">$</span>'
+    assert_includes result, '<span class="sh-command">bundle</span>'
+    assert_includes result, '<span class="sh-option">-A</span>'
+
+    # Complex git command
+    result = highlight('$ git commit -m "Fix bug" --no-verify')
+    assert_includes result, '<span class="sh-prompt">$</span>'
+    assert_includes result, '<span class="sh-command">git</span>'
+    assert_includes result, '<span class="sh-option">-m</span>'
+    assert_includes result, '<span class="sh-string">&quot;Fix bug&quot;</span>'
+    assert_includes result, '<span class="sh-option">--no-verify</span>'
+  end
+
+  def test_multiline_with_comments
+    code = <<~SHELL
+      # Generate documentation (creates _site directory)
+      bundle exec rake rdoc
+
+      # Force regenerate documentation
+      bundle exec rake rerdoc
+    SHELL
+
+    result = highlight(code)
+    assert_includes result, '<span class="sh-comment"># Generate documentation (creates _site directory)</span>'
+    assert_includes result, '<span class="sh-comment"># Force regenerate documentation</span>'
+  end
+
+  def test_empty_and_whitespace
+    assert_equal '', highlight('')
+    assert_equal "   \n\t  \n  ", highlight("   \n\t  \n  ")
+  end
+
+  def test_html_escaping
+    result = highlight('echo "<script>alert(1)</script>"')
+    assert_includes result, '&lt;script&gt;'
+    assert_includes result, '&lt;/script&gt;'
+
+    result = highlight('echo "a && b"')
+    assert_includes result, '&amp;&amp;'
+  end
+
+  private
+
+  def highlight(code)
+    @context.eval("highlightShell(#{code.to_json})")
+  end
+end