jekyll-mermaid-prebuild 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad9dfff47c169ef73600de5d11407d536e0b16003ad4297e6bab55470aded883
-  data.tar.gz: 214c1fe4e08e38927c85415aab82eaa542820c07ee5aa4d356e045799d4f34bc
+  metadata.gz: 1a6f44826b0694bbba4cea5d5b0272301e8909003a9b182eb340042c80454ebb
+  data.tar.gz: 9f632d879d948c8030edc5365bc06bc75bd36809da017fd35c6f20ee5b252b0a
 SHA512:
-  metadata.gz: 53beefcd83cc729cc7aea99d55ca7a322b7858c616784f57dc2556ccb4b03ab740643ebe03a72c2a57acf754d197d2d8a911ccacc03b909a408631e4af25feee
-  data.tar.gz: f9f97e2f5c6539994ff13612c22d06717f817f19cfec5ff471b4dc7cdcd474fe931fa277e6ba5ec4cc93226b1c0c999b7ca16e16a583aac188abc057c4113b1e
+  metadata.gz: 88b628146a89abbc660bda67b254653a1e77b74b63d55c4ba882a2abe600804129fe29405df0a720457bfbbcbf19b14e7d7841fea322835274deffdcd21c3e67
+  data.tar.gz: 3ce40596559ad01778c875cf599b693f42ee1477c70ab178f0f94ff4e735bbe1e1392d68430f2c3985b61ca82b1d8851f9e292715a501a10faf1c640d9dd001e

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [0.6.0](https://github.com/Texarkanine/jekyll-mermaid-prebuild/compare/v0.5.0...v0.6.0) (2026-07-19)
+
+
+### ⚠ BREAKING CHANGES
+
+* **test:** add Mutant mutation testing with 100% kill ([#44](https://github.com/Texarkanine/jekyll-mermaid-prebuild/issues/44))
+
+### Features
+
+* **test:** add Mutant mutation testing with 100% kill ([#44](https://github.com/Texarkanine/jekyll-mermaid-prebuild/issues/44)) ([e86a82a](https://github.com/Texarkanine/jekyll-mermaid-prebuild/commit/e86a82a6eba5dc0fc037ff0f3451d12708a4f629))
+
+
+### Bug Fixes
+
+* **deps-dev:** migrate SimpleCov add_filter to skip ([#41](https://github.com/Texarkanine/jekyll-mermaid-prebuild/issues/41)) ([#42](https://github.com/Texarkanine/jekyll-mermaid-prebuild/issues/42)) ([bc068f0](https://github.com/Texarkanine/jekyll-mermaid-prebuild/commit/bc068f0268e2d974a061a1474d0973306d860f8e))
+
+## [0.5.0](https://github.com/Texarkanine/jekyll-mermaid-prebuild/compare/v0.4.0...v0.5.0) (2026-03-22)
+
+
+### Features
+
+* support "dark mode" (resolves [#11](https://github.com/Texarkanine/jekyll-mermaid-prebuild/issues/11)) ([#20](https://github.com/Texarkanine/jekyll-mermaid-prebuild/issues/20)) ([1ae9322](https://github.com/Texarkanine/jekyll-mermaid-prebuild/commit/1ae93225d9f6089d3d85ce18d06f44310fea3895))
+
 ## [0.4.0](https://github.com/Texarkanine/jekyll-mermaid-prebuild/compare/v0.3.2...v0.4.0) (2026-03-22)
 
 

data/README.md

@@ -94,6 +94,12 @@ Add to your `_config.yml`:
 mermaid_prebuild:
   enabled: true          # default: true
   output_dir: assets/svg # default: assets/svg
+  prefers-color-scheme:
+    mode: light          # light (default) | dark | auto — see [Color scheme](#color-scheme-mermaid-theme)
+    # Optional: override mmdc’s root SVG background (defaults: light=white, dark=black)
+    # background-color:
+    #   light: white
+    #   dark: black
   postprocessing:
     text_centering: true         # default: true
     overflow_protection: true    # default: true
@@ -108,6 +114,7 @@ mermaid_prebuild:
 |--------|---------|-------------|
 | `enabled` | `true` | Enable/disable the plugin |
 | `output_dir` | `assets/svg` | Directory for generated SVG files |
+| `prefers-color-scheme` | see below | **Hash** with `mode` (`light` / `dark` / `auto`) and optional `background-color` for chart backgrounds. See [Color scheme](#color-scheme-mermaid-theme). |
 
 #### `postprocessing` group
 
@@ -120,6 +127,31 @@ All cross-browser rendering fixes live under the `postprocessing:` key. Each can
 | `edge_label_padding` | `0` | Extra SVG user units added to edge-label `<foreignObject>` widths after mmdc (off when `0`, `false`, or omitted). Applies to all diagram types. See [Cross-browser text rendering fixes](#cross-browser-text-rendering-fixes). |
 | `emoji_width_compensation` | `{}` | Map of diagram types to booleans; see [Emoji width compensation](#emoji-width-compensation) below. |
 
+### Color scheme (Mermaid theme)
+
+Under `mermaid_prebuild`, the **`prefers-color-scheme`** key (hyphenated, like the CSS media feature) must be a **YAML mapping**. Use `mode` for the Mermaid theme / HTML behavior. Optionally nest **`background-color`** (same spelling as in CSS) with `light` / `dark` slots for each chart variant’s root SVG fill (mmdc always emits `background-color: white` on the root `<svg>`; the plugin rewrites that per file).
+
+```yaml
+mermaid_prebuild:
+  prefers-color-scheme:
+    mode: auto
+    background-color:
+      light: white         # default if omitted
+      dark: black          # default if omitted
+```
+
+| `mode` | Behavior |
+|--------|----------|
+| `light` | One SVG per diagram using Mermaid’s default (light) theme. |
+| `dark` | One SVG per diagram using mmdc’s dark theme (`mmdc -t dark`). |
+| `auto` | Two SVGs per diagram: `{digest}.svg` (light) and `{digest}-dark.svg` (dark). The embedded HTML uses two links with a small inline stylesheet so only the variant matching the visitor’s `prefers-color-scheme` is shown. **Build cost:** each diagram runs `mmdc` twice until both files are cached. |
+
+**Chart backgrounds:** Values are injected verbatim into the root `<svg style="...">` as the CSS token after `background-color:` (for example `white`, `black`, `#fff0aa`, `rgb(0,0,0)`, `transparent`). They are validated conservatively: values containing quotes, angle brackets, backticks, semicolons, backslashes, or control characters are rejected and the default for that slot is used, with a warning. Keep values short (max 256 characters). **Do not** put raw double quotes or HTML in these strings.
+
+**Transparency:** The standard CSS keyword **`transparent`** is supported and is the usual choice when you want that variant’s chart to show the page behind it (for example `dark: transparent` on a dark-themed site). Fully transparent RGBA such as `rgba(0, 0, 0, 0)` is also valid if you prefer explicit alpha.
+
+If `prefers-color-scheme` is not a hash (for example a bare string), the plugin uses `mode: light` and default backgrounds and logs a warning. Unknown `mode` values fall back to `light` with a warning. Omitting `mode` is treated as `light`.
+
 ### Cross-browser text rendering fixes
 
 When mmdc renders a diagram, headless Chromium measures text with `getBoundingClientRect()` and sets each `<foreignObject>` to exactly that width. If the viewing browser (different OS, different fonts) renders the same text at a different width, labels can clip or shift. The plugin can apply some fixes to every generated SVG (all configurable under `postprocessing:`):
@@ -179,7 +211,7 @@ Generated SVGs are cached in `.jekyll-cache/jekyll-mermaid-prebuild/`. The cache
 - Modified diagrams are automatically regenerated
 - Different diagrams with different content get different cache keys
 - Enabling or disabling emoji width compensation for a diagram type invalidates cache for that content (keys include compensated source when applicable)
-- Changing `edge_label_padding`, `text_centering`, or `overflow_protection` invalidates cache keys
+- Changing `edge_label_padding`, `text_centering`, `overflow_protection`, `prefers-color-scheme` mode, or chart background colors invalidates cache keys
 
 To clear the cache:
 

data/jekyll-mermaid-prebuild.gemspec

@@ -35,11 +35,13 @@ Gem::Specification.new do |spec|
   spec.add_dependency "jekyll", ">= 4.0", "< 5.0"
 
   # Development dependencies
+  spec.add_development_dependency "mutant", "~> 0.16"
+  spec.add_development_dependency "mutant-rspec", "~> 0.16"
   spec.add_development_dependency "rake", "~> 13.3"
   spec.add_development_dependency "rspec", "~> 3.13"
   spec.add_development_dependency "rubocop", "~> 1.81"
   spec.add_development_dependency "rubocop-rake", "~> 0.7"
   spec.add_development_dependency "rubocop-rspec", "~> 3.8"
-  spec.add_development_dependency "simplecov", "~> 0.22"
-  spec.add_development_dependency "simplecov-cobertura", "~> 3.1"
+  spec.add_development_dependency "simplecov", "~> 1.0"
+  spec.add_development_dependency "simplecov-cobertura", "~> 4.0"
 end

data/lib/jekyll-mermaid-prebuild/configuration.rb

@@ -5,8 +5,19 @@ module JekyllMermaidPrebuild
   class Configuration
     DEFAULT_OUTPUT_DIR = "assets/svg"
     CACHE_DIR = ".jekyll-cache/jekyll-mermaid-prebuild"
+    DEFAULT_CHART_BG_LIGHT = "white"
+    DEFAULT_CHART_BG_DARK = "black"
+    # Parsed mode when PCS is omitted, invalid, or empty (not the YAML string "light").
+    DEFAULT_PREFERS_COLOR_SCHEME_MODE = :light
+    MAX_CHART_BACKGROUND_LENGTH = 256
+    INVALID_CHART_BACKGROUND = /[\x00-\x1f"'<>;`\\]/
 
-    attr_reader :output_dir, :text_centering, :overflow_protection, :edge_label_padding, :emoji_width_compensation
+    # YAML keys under mermaid_prebuild — hyphenated to align with CSS (@media (prefers-color-scheme), background-color).
+    PREFERS_COLOR_SCHEME_YAML_KEY = "prefers-color-scheme"
+    BACKGROUND_COLOR_YAML_KEY = "background-color"
+
+    attr_reader :output_dir, :text_centering, :overflow_protection, :edge_label_padding, :emoji_width_compensation,
+                :prefers_color_scheme, :chart_background_light, :chart_background_dark
 
     # Initialize configuration from Jekyll site
     #
@@ -15,6 +26,8 @@ module JekyllMermaidPrebuild
       config = site.config["mermaid_prebuild"] || {}
       @output_dir = parse_output_dir(config["output_dir"])
       @enabled = config.fetch("enabled", true)
+      pcs_raw = config[PREFERS_COLOR_SCHEME_YAML_KEY]
+      parse_prefers_color_scheme(pcs_raw)
 
       pp = config["postprocessing"] || {}
       @text_centering = pp.fetch("text_centering", true)
@@ -37,7 +50,99 @@ module JekyllMermaidPrebuild
       CACHE_DIR
     end
 
-    private
+    # Parse the prefers-color-scheme block (see PREFERS_COLOR_SCHEME_YAML_KEY) from a Hash only
+    # (mode + optional background-color map). Non-Hash values fall back to :light and default
+    # backgrounds with a warning.
+    #
+    # @param value [Object] raw site config value
+    # @return [void]
+    def parse_prefers_color_scheme(value)
+      if !value.nil? && !value.is_a?(Hash)
+        Jekyll.logger.warn(
+          "MermaidPrebuild:",
+          "Invalid #{PREFERS_COLOR_SCHEME_YAML_KEY} (expected a Hash); " \
+          "using light mode and default backgrounds"
+        )
+      end
+
+      mode_raw = config_hash_fetch(value, "mode")
+      @prefers_color_scheme = normalize_prefers_mode(mode_raw)
+
+      bg_container = config_hash_fetch(value, BACKGROUND_COLOR_YAML_KEY)
+      light_raw = config_hash_fetch(bg_container, "light")
+      dark_raw = config_hash_fetch(bg_container, "dark")
+      @chart_background_light = coerce_chart_background(light_raw, DEFAULT_CHART_BG_LIGHT, "light")
+      @chart_background_dark = coerce_chart_background(dark_raw, DEFAULT_CHART_BG_DARK, "dark")
+    end
+
+    # @param raw [Object]
+    # @return [Symbol] :light, :dark, or :auto
+    def normalize_prefers_mode(raw)
+      s = raw.to_s.strip.downcase
+      return DEFAULT_PREFERS_COLOR_SCHEME_MODE if s.empty?
+
+      case s
+      when "light" then :light
+      when "dark" then :dark
+      when "auto" then :auto
+      else
+        Jekyll.logger.warn(
+          "MermaidPrebuild:",
+          "Invalid #{PREFERS_COLOR_SCHEME_YAML_KEY} mode #{raw.inspect}; using light"
+        )
+        DEFAULT_PREFERS_COLOR_SCHEME_MODE
+      end
+    end
+
+    # Read a config key from a Hash (string key as in YAML, or matching Symbol).
+    #
+    # @param hash [Hash]
+    # @param key [String] exact key (e.g. "mode", "background-color", "light")
+    # @return [Object, nil]
+    def config_hash_fetch(hash, key)
+      return nil unless hash.is_a?(Hash)
+
+      hash.fetch(key) { hash.fetch(key.to_sym, nil) }
+    end
+
+    # @param value [Object] raw color string or nil (use default)
+    # @param default [String] fallback literal
+    # @param label [String] "light" or "dark" for logging
+    # @return [String] frozen sanitized CSS fragment
+    def coerce_chart_background(value, default, label)
+      return finalize_background(default) if value.nil?
+
+      str = value.to_s.strip
+      if str.empty?
+        Jekyll.logger.warn "MermaidPrebuild:",
+                           "Invalid chart background (#{label}): empty string; using #{default.inspect}"
+        return finalize_background(default)
+      end
+
+      if str.length > MAX_CHART_BACKGROUND_LENGTH
+        Jekyll.logger.warn "MermaidPrebuild:",
+                           "Invalid chart background (#{label}): value too long; using #{default.inspect}"
+        return finalize_background(default)
+      end
+
+      if chart_background_invalid?(str)
+        Jekyll.logger.warn "MermaidPrebuild:",
+                           "Invalid chart background (#{label}): disallowed characters; using #{default.inspect}"
+        return finalize_background(default)
+      end
+
+      str.freeze
+    end
+
+    def chart_background_invalid?(value)
+      INVALID_CHART_BACKGROUND.match?(value)
+    end
+
+    # @param value [String]
+    # @return [String] frozen copy
+    def finalize_background(value)
+      value.to_s.dup.freeze
+    end
 
     # Returns a frozen Hash of diagram type (string) => boolean. Non-hash values are rejected → {}.
     #
@@ -46,7 +151,7 @@ module JekyllMermaidPrebuild
     def parse_emoji_width_compensation(value)
       return {}.freeze unless value.is_a?(Hash)
 
-      result = value.transform_keys(&:to_s).transform_values { |v| [true, false].include?(v) ? v : false }
+      result = value.transform_keys(&:to_s).transform_values { |v| v == true }
       result.freeze
     end
 
@@ -56,18 +161,15 @@ module JekyllMermaidPrebuild
       dir = dir.strip
       return DEFAULT_OUTPUT_DIR if dir.empty?
 
-      dir.gsub(%r{^/+|/+$}, "")
+      dir.split("/").reject(&:empty?).join("/")
     end
 
     # @param value [Object] raw config (numeric or off)
     # @return [Numeric] non-negative padding in SVG user units; 0 means disabled
     def parse_edge_label_padding(value)
-      return 0 if value.nil? || value == false
-
-      num = value.is_a?(Numeric) ? value : nil
-      return 0 unless num
+      return 0 unless value.is_a?(Numeric)
 
-      num.negative? ? 0 : num
+      value.negative? ? 0 : value
     end
   end
 end

data/lib/jekyll-mermaid-prebuild/digest_calculator.rb

@@ -5,13 +5,11 @@ require "digest"
 module JekyllMermaidPrebuild
   # Computes content-based digests for caching
   module DigestCalculator
-    module_function
-
     # Generate a short digest for mermaid content
     #
     # @param content [String] mermaid diagram source
     # @return [String] 8-character hex digest
-    def content_digest(content)
+    def self.content_digest(content)
       Digest::MD5.hexdigest(content)[0, 8]
     end
   end

data/lib/jekyll-mermaid-prebuild/emoji_compensator.rb

@@ -4,8 +4,6 @@ module JekyllMermaidPrebuild
   # Stateless module: compensates for headless Chromium emoji width undermeasurement
   # by appending   padding to emoji-containing node labels before mmdc renders.
   module EmojiCompensator
-    module_function
-
     # Match a single Extended_Pictographic codepoint (emoji).
     EMOJI_RE = /\p{Extended_Pictographic}/
 
@@ -15,28 +13,22 @@ module JekyllMermaidPrebuild
     #
     # @param mermaid_source [String] raw Mermaid diagram source
     # @return [String, nil] diagram type keyword (e.g. "flowchart", "sequenceDiagram") or nil
-    def detect_diagram_type(mermaid_source)
-      return nil if !mermaid_source || mermaid_source.strip.empty?
+    def self.detect_diagram_type(mermaid_source)
+      return nil unless mermaid_source
 
       in_frontmatter = false
-      frontmatter_delim_count = 0
 
       mermaid_source.each_line do |line|
         stripped = line.strip
-        # Track YAML frontmatter
         if stripped == "---"
-          frontmatter_delim_count += 1
-          in_frontmatter = frontmatter_delim_count.odd?
+          in_frontmatter = !in_frontmatter
           next
         end
         next if in_frontmatter
         next if stripped.empty?
         next if stripped.start_with?("%%")
 
-        # First token of first non-skipped line
-        token = stripped.split(/\s+/, 2).first
-        return nil if token.nil? || token.empty?
-
+        token = stripped[/\A\S+/]
         return token == "graph" ? "flowchart" : token
       end
 
@@ -49,10 +41,10 @@ module JekyllMermaidPrebuild
     # @param mermaid_source [String] Mermaid diagram source
     # @param diagram_type [String] result of detect_diagram_type
     # @return [String] possibly modified source
-    def compensate(mermaid_source, diagram_type)
-      return mermaid_source if diagram_type != "flowchart"
+    def self.compensate(mermaid_source, diagram_type)
+      return compensate_flowchart_labels(mermaid_source) if diagram_type == "flowchart"
 
-      compensate_flowchart_labels(mermaid_source)
+      mermaid_source
     end
 
     BR_RE = %r{(<br\s*/?>)}i
@@ -62,7 +54,7 @@ module JekyllMermaidPrebuild
     #
     # @param text [String]
     # @return [Integer]
-    def count_emoji(text)
+    def self.count_emoji(text)
       text.scan(EMOJI_RE).length
     end
 
@@ -71,46 +63,48 @@ module JekyllMermaidPrebuild
     #
     # @param text [String]
     # @return [Integer]
-    def visual_length(text)
+    def self.visual_length(text)
       text.length + count_emoji(text)
     end
 
     # Pad the longest line in a label if it contains emoji.
     # Splits on <br/> variants, finds the visually longest line, and only
     # pads that line (shorter lines center naturally in the wider container).
-    # Returns content unchanged if the longest line has no emoji.
+    # When no padding is applied, returns the same String object (identity),
+    # not merely an equal copy.
     #
     # @param content [String] raw label text (may contain <br/> line breaks)
     # @return [String] possibly padded label text
-    def pad_label_content(content)
-      parts = content.split(BR_RE)
-      line_indices = (0...parts.length).step(2).to_a
-      return content if line_indices.empty?
-
-      longest_part_idx = line_indices.max_by { |i| visual_length(parts[i]) }
-      longest_line = parts[longest_part_idx]
-      n = count_emoji(longest_line)
-      return content unless n.positive?
-
-      parts[longest_part_idx] = "#{longest_line}#{NBSP * (n * 2)}"
-      parts.join
+    def self.pad_label_content(content)
+      segments = content.split(BR_RE)
+      # Even indices are text lines; odd indices are the captured <br> delimiters.
+      line_pairs = segments.each_with_index.select { |_segment, index| index.even? }
+      return content if line_pairs.empty?
+
+      # max_by keeps the first of equal-length ties — pad that one index only.
+      longest_line, longest_idx = line_pairs.max_by { |segment, _index| visual_length(segment) }
+      emoji_count = count_emoji(longest_line)
+      return content unless emoji_count.positive?
+
+      segments[longest_idx] = "#{longest_line}#{NBSP * (emoji_count * 2)}"
+      segments.join
     end
 
-    def compensate_flowchart_labels(source)
-      result = source.dup
+    def self.compensate_flowchart_labels(source)
+      result = source
 
       [
-        [/\["(.*?)"\]/m, '["', '"]'],
-        [/\['(.*?)'\]/m, "['", "']"],
-        [/\("(.*?)"\)/m, '("', '")'],
-        [/\{"(.*?)"\}/m, '{"', '"}']
+        [/\["(.+?)"\]/m, '["', '"]'],
+        [/\['(.+?)'\]/m, "['", "']"],
+        [/\("(.+?)"\)/m, '("', '")'],
+        [/\{"(.+?)"\}/m, '{"', '"}']
       ].each do |regex, open_str, close_str|
         result = result.gsub(regex) do
           "#{open_str}#{pad_label_content(Regexp.last_match(1))}#{close_str}"
         end
       end
 
-      result.gsub(%r{\[/"((?:[^"\\]|\\.)*)"/\]}m) do
+      result.gsub(%r{\[/"((?:[^"\\]|\\.)+?)"/\]}) do
         "[/\"#{pad_label_content(Regexp.last_match(1))}\"/]"
       end
     end

data/lib/jekyll-mermaid-prebuild/generator.rb

@@ -18,29 +18,21 @@ module JekyllMermaidPrebuild
     #
     # @param mermaid_source [String] mermaid diagram definition
     # @param cache_key [String] digest for caching
-    # @param diagram_type [String, nil] from EmojiCompensator.detect_diagram_type (e.g. "block")
-    # @return [String, nil] path to cached SVG file or nil on failure
-    def generate(mermaid_source, cache_key, diagram_type: nil)
-      cache_path = File.join(@config.cache_dir, "#{cache_key}.svg")
-
-      # Return cached file if it exists
-      return cache_path if File.exist?(cache_path)
-
-      # Ensure cache directory exists
-      FileUtils.mkdir_p(@config.cache_dir)
-
-      # Generate SVG using mmdc
-      success = MmdcWrapper.render(mermaid_source, cache_path)
-      return nil unless success
-
-      post_process_svg(cache_path, diagram_type)
-
-      cache_path
+    # @return [Hash{String => String}, nil] stem (cache filename without .svg) => absolute cache path, or nil on failure
+    def generate(mermaid_source, cache_key)
+      case @config.prefers_color_scheme
+      when :light
+        generate_one(mermaid_source, cache_key, theme: :default)
+      when :dark
+        generate_one(mermaid_source, cache_key, theme: :dark)
+      when :auto
+        generate_auto(mermaid_source, cache_key)
+      end
     end
 
-    # Build SVG URL from cache key
+    # Build SVG URL from cache key (stem, e.g. digest or digest-dark)
     #
-    # @param cache_key [String] the cache key
+    # @param cache_key [String] the cache stem
     # @return [String] URL path to SVG
     def build_svg_url(cache_key)
       "/#{@config.output_dir}/#{cache_key}.svg"
@@ -48,9 +40,27 @@ module JekyllMermaidPrebuild
 
     # Build figure HTML for a diagram
     #
-    # @param svg_url [String] URL to the SVG file
+    # @param svg_url [String] URL to the light (or only) SVG file
+    # @param dark_url [String, nil] when set (auto mode), second link + CSS toggle for prefers-color-scheme
     # @return [String] HTML figure element
-    def build_figure_html(svg_url)
+    def build_figure_html(svg_url, dark_url: nil)
+      if dark_url
+        return <<~HTML
+          <figure class="mermaid-diagram">
+          <style>
+          .mermaid-diagram__light { display: inline; }
+          .mermaid-diagram__dark { display: none; }
+          @media (prefers-color-scheme: dark) {
+            .mermaid-diagram__light { display: none; }
+            .mermaid-diagram__dark { display: inline; }
+          }
+          </style>
+          <a class="mermaid-diagram__light" href="#{svg_url}"><img src="#{svg_url}" alt="Mermaid Diagram"></a>
+          <a class="mermaid-diagram__dark" href="#{dark_url}"><img src="#{dark_url}" alt="Mermaid Diagram"></a>
+          </figure>
+        HTML
+      end
+
       <<~HTML
         <figure class="mermaid-diagram">
         <a href="#{svg_url}"><img src="#{svg_url}" alt="Mermaid Diagram"></a>
@@ -60,17 +70,54 @@ module JekyllMermaidPrebuild
 
     private
 
-    def post_process_svg(cache_path, _diagram_type)
+    # @return [Hash{String => String}, nil]
+    def generate_one(mermaid_source, stem, theme:)
+      cache_path = File.join(@config.cache_dir, "#{stem}.svg")
+      return { stem => cache_path } if File.exist?(cache_path)
+
+      FileUtils.mkdir_p(@config.cache_dir)
+      return nil unless MmdcWrapper.render(mermaid_source, cache_path, theme: theme)
+
+      bg = theme == :dark ? @config.chart_background_dark : @config.chart_background_light
+      post_process_svg(cache_path, root_background: bg)
+      { stem => cache_path }
+    end
+
+    # @return [Hash{String => String}, nil]
+    def generate_auto(mermaid_source, cache_key)
+      light_stem = cache_key
+      dark_stem = "#{cache_key}-dark"
+      light_path = File.join(@config.cache_dir, "#{light_stem}.svg")
+      dark_path = File.join(@config.cache_dir, "#{dark_stem}.svg")
+
+      FileUtils.mkdir_p(@config.cache_dir)
+
+      unless File.exist?(light_path)
+        return nil unless MmdcWrapper.render(mermaid_source, light_path, theme: :default)
+
+        post_process_svg(light_path, root_background: @config.chart_background_light)
+      end
+
+      unless File.exist?(dark_path)
+        return nil unless MmdcWrapper.render(mermaid_source, dark_path, theme: :dark)
+
+        post_process_svg(dark_path, root_background: @config.chart_background_dark)
+      end
+
+      { light_stem => light_path, dark_stem => dark_path }
+    end
+
+    def post_process_svg(cache_path, root_background:)
       raw = File.read(cache_path)
       svg = raw
 
       svg = SvgPostProcessor.ensure_text_centering(svg) if @config.text_centering
       svg = SvgPostProcessor.ensure_foreignobject_overflow(svg) if @config.overflow_protection
+      svg = SvgPostProcessor.apply_root_svg_background(svg, root_background)
 
-      pad = @config.edge_label_padding
-      svg = SvgPostProcessor.apply(svg, padding: pad) if pad.is_a?(Numeric) && pad.positive?
+      svg = SvgPostProcessor.apply(svg, padding: @config.edge_label_padding)
 
-      File.write(cache_path, svg) if svg != raw
+      File.write(cache_path, svg) unless svg.eql?(raw)
     end
   end
 end

data/lib/jekyll-mermaid-prebuild/hooks.rb

@@ -5,15 +5,13 @@ require "fileutils"
 module JekyllMermaidPrebuild
   # Jekyll hook integration
   module Hooks
-    module_function
-
     # Copy generated SVGs to _site directory
     #
     # @param site [Jekyll::Site] the Jekyll site
     # @param config [Configuration] plugin configuration
     # @param svgs [Hash] cache_key => cached_path mapping
-    def copy_svgs_to_site(site, config, svgs)
-      return unless svgs && !svgs.empty?
+    def self.copy_svgs_to_site(site, config, svgs)
+      return if svgs.nil? || svgs.empty?
 
       dest_dir = File.join(site.dest, config.output_dir)
       FileUtils.mkdir_p(dest_dir)
@@ -34,110 +32,110 @@ module JekyllMermaidPrebuild
     end
 
     # Log helpful error message for Puppeteer issues
-    def log_puppeteer_error
-      Jekyll.logger.error "MermaidPrebuild:", "=" * 60
+    def self.log_puppeteer_error
       Jekyll.logger.error "MermaidPrebuild:", "mmdc failed: Puppeteer cannot launch headless Chrome"
-      Jekyll.logger.error "MermaidPrebuild:", ""
-      Jekyll.logger.error "MermaidPrebuild:", "This usually means missing system libraries."
-      Jekyll.logger.error "MermaidPrebuild:", "On Debian/Ubuntu/WSL, install with:"
-      Jekyll.logger.error "MermaidPrebuild:", ""
-      Jekyll.logger.error "MermaidPrebuild:", "  sudo apt-get update"
-      Jekyll.logger.error "MermaidPrebuild:", "  sudo apt-get install -y libgbm1 libasound2 libatk1.0-0 \\"
-      Jekyll.logger.error "MermaidPrebuild:", "    libatk-bridge2.0-0 libcups2 libdrm2 libxcomposite1 \\"
-      Jekyll.logger.error "MermaidPrebuild:", "    libxdamage1 libxfixes3 libxrandr2 libxkbcommon0 \\"
-      Jekyll.logger.error "MermaidPrebuild:", "    libpango-1.0-0 libcairo2 libnss3 libnspr4"
-      Jekyll.logger.error "MermaidPrebuild:", ""
-      Jekyll.logger.error "MermaidPrebuild:", "See: https://pptr.dev/troubleshooting"
-      Jekyll.logger.error "MermaidPrebuild:", "=" * 60
+      Jekyll.logger.error "MermaidPrebuild:", "Install system libraries (see https://pptr.dev/troubleshooting)"
     end
 
-    # Register Jekyll hooks
-    def register
-      # Initialize and check mmdc after site data is loaded
-      Jekyll::Hooks.register :site, :post_read do |site|
-        config = Configuration.new(site)
-        site.data["mermaid_prebuild_config"] = config
+    # Initialize plugin state after site data is loaded (:post_read)
+    #
+    # @param site [Jekyll::Site] the Jekyll site
+    def self.initialize_system(site)
+      config = Configuration.new(site)
+      site.data["mermaid_prebuild_config"] = config
+
+      unless config.enabled?
+        Jekyll.logger.info "MermaidPrebuild:", "Disabled in configuration"
+        site.data["mermaid_prebuild_enabled"] = false
+        return
+      end
 
-        unless config.enabled?
-          Jekyll.logger.info "MermaidPrebuild:", "Disabled in configuration"
-          site.data["mermaid_prebuild_enabled"] = false
-          next
-        end
+      status = MmdcWrapper.check_status
+
+      case status
+      when :ok
+        Jekyll.logger.info "MermaidPrebuild:", "Initialized (mmdc #{MmdcWrapper.version || "unknown version"})"
+        Jekyll.logger.info "MermaidPrebuild:", "Output directory: #{config.output_dir}"
+        site.data["mermaid_prebuild_enabled"] = true
+        generator = Generator.new(config)
+        site.data["mermaid_prebuild_generator"] = generator
+        site.data["mermaid_prebuild_processor"] = Processor.new(config, generator)
+        site.data["mermaid_prebuild_svgs"] = {}
+      when :not_found
+        Jekyll.logger.warn "MermaidPrebuild:", "mmdc not found - mermaid diagrams will not be converted"
+        Jekyll.logger.warn "MermaidPrebuild:", "Install with: npm install -g @mermaid-js/mermaid-cli"
+        site.data["mermaid_prebuild_enabled"] = false
+      when :puppeteer_error
+        log_puppeteer_error
+        site.data["mermaid_prebuild_enabled"] = false
+      else
+        Jekyll.logger.warn "MermaidPrebuild:", "mmdc check failed with unknown error"
+        site.data["mermaid_prebuild_enabled"] = false
+      end
+    end
+
+    # Process documents/pages before rendering (:pre_render)
+    #
+    # @param site [Jekyll::Site] the Jekyll site
+    def self.process_site(site)
+      return unless site.data["mermaid_prebuild_enabled"]
+
+      processor = site.data["mermaid_prebuild_processor"]
+      total_count = 0
+
+      site.documents.each do |document|
+        next unless document.content
 
-        status = MmdcWrapper.check_status
-
-        case status
-        when :ok
-          Jekyll.logger.info "MermaidPrebuild:", "Initialized (mmdc #{MmdcWrapper.version || "unknown version"})"
-          Jekyll.logger.info "MermaidPrebuild:", "Output directory: #{config.output_dir}"
-          site.data["mermaid_prebuild_enabled"] = true
-          site.data["mermaid_prebuild_generator"] = Generator.new(config)
-          site.data["mermaid_prebuild_processor"] = Processor.new(config, site.data["mermaid_prebuild_generator"])
-          site.data["mermaid_prebuild_svgs"] = {}
-        when :not_found
-          Jekyll.logger.warn "MermaidPrebuild:", "mmdc not found - mermaid diagrams will not be converted"
-          Jekyll.logger.warn "MermaidPrebuild:", "Install with: npm install -g @mermaid-js/mermaid-cli"
-          site.data["mermaid_prebuild_enabled"] = false
-        when :puppeteer_error
-          log_puppeteer_error
-          site.data["mermaid_prebuild_enabled"] = false
-        else
-          Jekyll.logger.warn "MermaidPrebuild:", "mmdc check failed with unknown error"
-          site.data["mermaid_prebuild_enabled"] = false
+        processed, count, svgs = processor.process_content(document.content, site)
+        if count.positive?
+          document.content = processed
+          site.data["mermaid_prebuild_svgs"].merge!(svgs)
+          Jekyll.logger.info "MermaidPrebuild:", "Converted #{count} diagram(s) in #{document.relative_path}"
+          total_count += count
         end
+      rescue StandardError => e
+        Jekyll.logger.error "MermaidPrebuild:", "Error processing #{document.relative_path}: #{e.message}"
       end
 
-      # Process all documents/pages BEFORE rendering
-      Jekyll::Hooks.register :site, :pre_render do |site|
-        next unless site.data["mermaid_prebuild_enabled"]
-
-        processor = site.data["mermaid_prebuild_processor"]
-        total_count = 0
-
-        # Process all documents
-        site.documents.each do |document|
-          next unless document.content
-
-          processed, count, svgs = processor.process_content(document.content, site)
-          if count.positive?
-            document.content = processed
-            site.data["mermaid_prebuild_svgs"].merge!(svgs)
-            Jekyll.logger.info "MermaidPrebuild:", "Converted #{count} diagram(s) in #{document.relative_path}"
-            total_count += count
-          end
-        rescue StandardError => e
-          Jekyll.logger.error "MermaidPrebuild:", "Error processing #{document.relative_path}: #{e.message}"
-        end
+      site.pages.each do |page|
+        next unless page.content
 
-        # Process all pages
-        site.pages.each do |page|
-          next unless page.content
-
-          processed, count, svgs = processor.process_content(page.content, site)
-          if count.positive?
-            page.content = processed
-            site.data["mermaid_prebuild_svgs"].merge!(svgs)
-            Jekyll.logger.info "MermaidPrebuild:", "Converted #{count} diagram(s) in #{page.relative_path}"
-            total_count += count
-          end
-        rescue StandardError => e
-          Jekyll.logger.error "MermaidPrebuild:", "Error processing page: #{e.message}"
+        processed, count, svgs = processor.process_content(page.content, site)
+        if count.positive?
+          page.content = processed
+          site.data["mermaid_prebuild_svgs"].merge!(svgs)
+          Jekyll.logger.info "MermaidPrebuild:", "Converted #{count} diagram(s) in #{page.relative_path}"
+          total_count += count
         end
-
-        Jekyll.logger.info "MermaidPrebuild:", "Total: #{total_count} diagram(s) converted" if total_count.positive?
+      rescue StandardError => e
+        Jekyll.logger.error "MermaidPrebuild:", "Error processing #{page.relative_path}: #{e.message}"
       end
 
-      # Copy SVGs to _site after write
-      Jekyll::Hooks.register :site, :post_write do |site|
-        next unless site.data["mermaid_prebuild_enabled"]
+      Jekyll.logger.info "MermaidPrebuild:", "Total: #{total_count} diagram(s) converted" if total_count.positive?
+    end
 
-        config = site.data["mermaid_prebuild_config"]
-        svgs = site.data["mermaid_prebuild_svgs"]
-        copy_svgs_to_site(site, config, svgs)
-      end
+    # Copy SVGs into _site after write (:post_write)
+    #
+    # @param site [Jekyll::Site] the Jekyll site
+    def self.copy_generated_svgs(site)
+      return unless site.data["mermaid_prebuild_enabled"]
+
+      config = site.data["mermaid_prebuild_config"]
+      svgs = site.data["mermaid_prebuild_svgs"]
+      copy_svgs_to_site(site, config, svgs)
     end
   end
 end
 
-# Register hooks when loaded
-JekyllMermaidPrebuild::Hooks.register
+# Register Jekyll hooks when loaded
+Jekyll::Hooks.register :site, :post_read do |site|
+  JekyllMermaidPrebuild::Hooks.initialize_system(site)
+end
+
+Jekyll::Hooks.register :site, :pre_render do |site|
+  JekyllMermaidPrebuild::Hooks.process_site(site)
+end
+
+Jekyll::Hooks.register :site, :post_write do |site|
+  JekyllMermaidPrebuild::Hooks.copy_generated_svgs(site)
+end

data/lib/jekyll-mermaid-prebuild/mmdc_wrapper.rb

@@ -6,39 +6,41 @@ require "tempfile"
 module JekyllMermaidPrebuild
   # Wrapper for mmdc (mermaid CLI) commands
   module MmdcWrapper
-    module_function
-
     # Check if mmdc is available in PATH
     #
     # @return [Boolean] true if mmdc is available
-    def available?
-      return @available if defined?(@available)
+    MMDC_COMMAND = "mmdc"
+
+    def self.available?
+      return @available if instance_variable_defined?(:@available)
 
-      @available = command_exists?("mmdc")
+      @available = command_exists?(MMDC_COMMAND)
     end
 
     # Check if a command exists in PATH (cross-platform)
     #
     # @param cmd [String] command name
     # @return [Boolean] true if command found
-    def command_exists?(cmd)
+    def self.command_exists?(cmd)
+      return false if cmd.nil? || cmd.empty?
+
       cmd_name = Gem.win_platform? ? "#{cmd}.exe" : cmd
       path_dirs = ENV.fetch("PATH", "").split(File::PATH_SEPARATOR)
 
       path_dirs.any? do |dir|
         executable = File.join(dir, cmd_name)
-        File.executable?(executable)
+        File.file?(executable) && File.executable?(executable)
       end
     end
 
     # Get mmdc version
     #
     # @return [String, nil] version string or nil
-    def version
-      return @version if defined?(@version)
+    def self.version
+      return @version if instance_variable_defined?(:@version)
 
-      output, status = Open3.capture2e("mmdc", "--version")
-      @version = status.success? ? output.strip : nil
+      output, status = Open3.capture2e(MMDC_COMMAND, "--version")
+      @version = output.strip if status.success?
     rescue StandardError
       @version = nil
     end
@@ -46,8 +48,8 @@ module JekyllMermaidPrebuild
     # Check mmdc status (availability and Puppeteer)
     #
     # @return [Symbol] :ok, :not_found, :puppeteer_error, or :unknown_error
-    def check_status
-      return @check_status if defined?(@check_status)
+    def self.check_status
+      return @check_status if instance_variable_defined?(:@check_status)
 
       unless available?
         @check_status = :not_found
@@ -58,25 +60,26 @@ module JekyllMermaidPrebuild
     end
 
     # Reset cached status (useful for testing)
-    def reset_cache!
-      remove_instance_variable(:@available) if defined?(@available)
-      remove_instance_variable(:@version) if defined?(@version)
-      remove_instance_variable(:@check_status) if defined?(@check_status)
+    def self.reset_cache!
+      remove_instance_variable(:@available) if instance_variable_defined?(:@available)
+      remove_instance_variable(:@version) if instance_variable_defined?(:@version)
+      remove_instance_variable(:@check_status) if instance_variable_defined?(:@check_status)
     end
 
     # Test mmdc with a minimal diagram to verify Puppeteer works
     #
     # @return [Symbol] :ok, :puppeteer_error, or :unknown_error
-    def test_render
-      input = Tempfile.new(["test", ".mmd"])
-      output = Tempfile.new(["test", ".svg"])
-
+    def self.test_render
+      input = Tempfile.new(["", ".mmd"])
+      output = Tempfile.new(["", ".svg"])
       begin
         input.write("graph TD\nA-->B")
         input.close
         output.close # Close before mmdc writes (Windows file locking)
 
-        _stdout, stderr, status = Open3.capture3("mmdc", "-i", input.path, "-o", output.path, "-e", "svg")
+        _stdout, stderr, status = Open3.capture3(
+          MMDC_COMMAND, "-i", input.path, "-o", output.path, "-e", "svg"
+        )
 
         if status.success?
           :ok
@@ -86,8 +89,8 @@ module JekyllMermaidPrebuild
           :unknown_error
         end
       ensure
-        input.close! rescue nil # rubocop:disable Style/RescueModifier
-        output.close! rescue nil # rubocop:disable Style/RescueModifier
+        input.unlink
+        output.unlink
       end
     end
 
@@ -95,15 +98,22 @@ module JekyllMermaidPrebuild
     #
     # @param mermaid_source [String] mermaid diagram definition
     # @param output_path [String] path to write SVG file
+    ALLOWED_RENDER_THEMES = %i[default dark].freeze
+
+    # @param theme [Symbol] :default (mermaid default theme) or :dark (mmdc -t dark)
     # @return [Boolean] true if successful
-    def render(mermaid_source, output_path)
+    # @raise [ArgumentError] if theme is not supported
+    def self.render(mermaid_source, output_path, theme: :default)
+      raise ArgumentError, "unsupported mmdc theme #{theme.inspect}" unless ALLOWED_RENDER_THEMES.include?(theme)
+
       input_file = Tempfile.new(["mermaid", ".mmd"])
 
       begin
         input_file.write(mermaid_source)
         input_file.close
 
-        cmd = ["mmdc", "-i", input_file.path, "-o", output_path, "-e", "svg"]
+        cmd = [MMDC_COMMAND, "-i", input_file.path, "-o", output_path, "-e", "svg"]
+        cmd += ["-t", "dark"] if theme == :dark
         _stdout, _stderr, status = Open3.capture3(*cmd)
 
         status.success?
@@ -116,7 +126,7 @@ module JekyllMermaidPrebuild
     # Supports both backtick (```) and tilde (~~~) fences with 3+ characters
     #
     # @return [Regexp] pattern matching mermaid code blocks
-    def mermaid_fence_pattern
+    def self.mermaid_fence_pattern
       /
         ^(`{3,}|~{3,})mermaid\s*\n  # Opening fence: 3+ backticks or tildes, then 'mermaid'
         (.*?)                        # Content (captured, non-greedy)

data/lib/jekyll-mermaid-prebuild/processor.rb

@@ -22,7 +22,7 @@ module JekyllMermaidPrebuild
     # @param _site [Jekyll::Site] the Jekyll site (unused, kept for API compatibility)
     # @return [Array<String, Integer, Hash>] [processed_content, count, svgs_to_copy]
     def process_content(content, _site = nil)
-      return [content, 0, {}] unless content
+      return [nil, 0, {}] unless content
 
       converted_count = 0
       svgs_to_copy = {}
@@ -36,21 +36,23 @@ module JekyllMermaidPrebuild
         result = convert_block(block)
         next unless result
 
+        result => { svgs:, html: }
+        block => { start:, end: block_end }
         converted_count += 1
-        svgs_to_copy[result[:cache_key]] = result[:cached_path]
-        processed[block[:start]...block[:end]] = result[:html]
+        svgs_to_copy.merge!(svgs)
+        processed[start...block_end] = html
       end
 
       [processed, converted_count, svgs_to_copy]
     end
 
-    private
-
     # @param source [String] mermaid passed to mmdc (after optional emoji compensation)
-    # @param diagram_type [String, nil]
     # @return [String] input to MD5 for cache key
-    def digest_string_for_cache(source, _diagram_type)
+    def digest_string_for_cache(source)
       parts = [source]
+      parts << "pcs=#{@config.prefers_color_scheme}"
+      parts << "bgL=#{@config.chart_background_light}"
+      parts << "bgD=#{@config.chart_background_dark}"
       parts << "tc=#{@config.text_centering}" unless @config.text_centering
       parts << "op=#{@config.overflow_protection}" unless @config.overflow_protection
       pad = @config.edge_label_padding
@@ -61,23 +63,30 @@ module JekyllMermaidPrebuild
     # Convert a single mermaid block to SVG
     #
     # @param block [Hash] block info with :content key
-    # @return [Hash, nil] {cache_key:, cached_path:, html:} or nil if failed
+    # @return [Hash, nil] {:svgs, :html} or nil if failed
     def convert_block(block)
       mermaid_source = block[:content]
       diagram_type = EmojiCompensator.detect_diagram_type(mermaid_source)
-      source_for_render = if diagram_type && @config.emoji_width_compensation[diagram_type]
+      source_for_render = if @config.emoji_width_compensation[diagram_type]
                             EmojiCompensator.compensate(mermaid_source, diagram_type)
                           else
                             mermaid_source
                           end
-      digest_input = digest_string_for_cache(source_for_render, diagram_type)
+      digest_input = digest_string_for_cache(source_for_render)
       cache_key = DigestCalculator.content_digest(digest_input)
-      cached_path = @generator.generate(source_for_render, cache_key, diagram_type: diagram_type)
+      paths = @generator.generate(source_for_render, cache_key)
+
+      return nil if paths.nil? || paths.empty?
 
-      return nil unless cached_path
+      light_url = @generator.build_svg_url(cache_key)
+      html = if @config.prefers_color_scheme == :auto
+               dark_url = @generator.build_svg_url("#{cache_key}-dark")
+               @generator.build_figure_html(light_url, dark_url: dark_url)
+             else
+               @generator.build_figure_html(light_url)
+             end
 
-      svg_url = @generator.build_svg_url(cache_key)
-      { cache_key: cache_key, cached_path: cached_path, html: @generator.build_figure_html(svg_url) }
+      { svgs: paths, html: html }
     end
 
     # Find all top-level mermaid code blocks (not nested inside other fences)
@@ -85,13 +94,14 @@ module JekyllMermaidPrebuild
     # @param content [String] markdown content
     # @return [Array<Hash>] array of {start:, end:, content:} for each top-level mermaid block
     def find_top_level_mermaid_blocks(content)
-      state = { blocks: [], fence_stack: [], current_mermaid: nil, position: 0 }
+      blocks = []
+      state = { blocks: blocks, fence_stack: [], position: 0 }
 
-      content.lines.each do |line|
+      content.lines do |line|
         process_line(line, state)
       end
 
-      state[:blocks]
+      blocks
     end
 
     # Process a single line for fence detection
@@ -102,8 +112,9 @@ module JekyllMermaidPrebuild
       match = line.match(FENCE_OPENER)
       if match
         handle_fence_line(line, line_start, match, state)
-      elsif state[:current_mermaid]
-        state[:current_mermaid][:content_lines] << line
+      elsif (current_mermaid = state[:current_mermaid])
+        content_lines = current_mermaid[:content_lines]
+        content_lines << line
       end
     end
 
@@ -111,7 +122,7 @@ module JekyllMermaidPrebuild
     def handle_fence_line(line, line_start, match, state)
       fence_chars = match[1]
       language = match[2]
-      fence_type = fence_chars[0]
+      fence_type = fence_chars.include?("~") ? "~" : "`"
       fence_length = fence_chars.length
 
       if state[:current_mermaid]
@@ -126,11 +137,14 @@ module JekyllMermaidPrebuild
     # Handle fence line while inside a mermaid block
     def handle_line_in_mermaid(line, fence_chars, fence_type, fence_length, state)
       cm = state[:current_mermaid]
+      blocks = state[:blocks]
+      position = state[:position]
+      content_lines = cm[:content_lines]
       if fence_type == cm[:fence_type] && fence_length == cm[:fence_length] && line.strip == fence_chars
-        state[:blocks] << { start: cm[:start], end: state[:position], content: cm[:content_lines].join }
+        blocks << { start: cm[:start], end: position, content: content_lines.join }
         state[:current_mermaid] = nil
       else
-        cm[:content_lines] << line
+        content_lines << line
       end
     end
 
@@ -146,12 +160,13 @@ module JekyllMermaidPrebuild
 
     # Handle fence line while inside a non-mermaid fence
     def handle_line_in_nested_fence(line, fence_type, fence_length, state)
-      top_fence_length, top_fence_type = state[:fence_stack].last
+      fence_stack = state[:fence_stack]
+      top_fence_length, top_fence_type = fence_stack.last
 
-      if fence_type == top_fence_type && fence_length >= top_fence_length && line.strip.match?(/^[`~]+$/)
-        state[:fence_stack].pop
+      if fence_type == top_fence_type && fence_length >= top_fence_length && line.strip.match?(/\A[`~]+\z/)
+        fence_stack.pop
       else
-        state[:fence_stack].push([fence_length, fence_type])
+        fence_stack.push([fence_length, fence_type])
       end
     end
   end

data/lib/jekyll-mermaid-prebuild/svg_post_processor.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 module JekyllMermaidPrebuild
-  # Post-processes mmdc-generated SVGs to fix cross-browser rendering issues.
+  # Post-processes mmdc-generated SVGs to fix rendering issues.
   #
-  # Three independent fixes:
+  # Four independent fixes:
   # 1. Text centering: Mermaid's CSS `text-align: center` targets SVG `<g>` elements where it
   #    has no effect on HTML inside `<foreignObject>`. We inject a CSS rule so that foreignObject
   #    content centers correctly regardless of text measurement differences between the generating
@@ -14,9 +14,10 @@ module JekyllMermaidPrebuild
   # 3. Edge label padding: Widens edge-label `<foreignObject>` widths in any diagram type to
   #    prevent clipping when the viewing browser renders text wider than headless Chromium measured.
   #    Opt-in via `postprocessing.edge_label_padding` config.
+  # 4. Root SVG background: mmdc always emits `background-color: white` on the root `<svg>` regardless
+  #    of theme. The plugin replaces that token with configurable CSS color values for light and
+  #    dark variants (defaults white / black) so charts match page background in both modes.
   module SvgPostProcessor
-    module_function
-
     # Opening sequence produced by mmdc for block edge labels (deterministic minified output).
     EDGE_LABEL_FOREIGN_OBJECT_RE = /
       (<g\sclass="edgeLabel"[^>]*><g\sclass="label"[^>]*><foreignObject)
@@ -27,9 +28,8 @@ module JekyllMermaidPrebuild
     # @param svg_string [String] full SVG document from mmdc
     # @param padding [Numeric] user units to add to each matching foreignObject width (must be positive)
     # @return [String] possibly widened SVG, or the original string on no-op / error
-    def apply(svg_string, padding:)
-      return svg_string unless svg_string.is_a?(String)
-      return svg_string unless padding.is_a?(Numeric) && padding.positive?
+    def self.apply(svg_string, padding:)
+      return svg_string unless padding.positive?
 
       apply_edge_label_padding(svg_string, padding)
     rescue StandardError
@@ -46,10 +46,8 @@ module JekyllMermaidPrebuild
     #
     # @param svg_string [String] full SVG document from mmdc
     # @return [String] SVG with overflow rule injected, or original on no-op / error
-    def ensure_foreignobject_overflow(svg_string)
-      return svg_string unless svg_string.is_a?(String)
+    def self.ensure_foreignobject_overflow(svg_string)
       return svg_string if svg_string.include?(OVERFLOW_RULE)
-      return svg_string unless svg_string.include?("</style>")
 
       svg_string.sub("</style>", "#{OVERFLOW_RULE}</style>")
     rescue StandardError
@@ -65,17 +63,33 @@ module JekyllMermaidPrebuild
     #
     # @param svg_string [String] full SVG document from mmdc
     # @return [String] SVG with centering rule injected, or original on no-op / error
-    def ensure_text_centering(svg_string)
-      return svg_string unless svg_string.is_a?(String)
+    def self.ensure_text_centering(svg_string)
       return svg_string if svg_string.include?(CENTERING_RULE)
-      return svg_string unless svg_string.include?("</style>")
 
       svg_string.sub("</style>", "#{CENTERING_RULE}</style>")
     rescue StandardError
       svg_string
     end
 
-    def apply_edge_label_padding(svg_string, padding)
+    # Replace `background-color: white` on the root <svg> style attribute with a caller-supplied
+    # CSS color (already sanitized by Configuration). Idempotent when mmdc output no longer contains
+    # the white token or the value already matches.
+    #
+    # @param svg_string [String] full SVG document from mmdc
+    # @param css_background [String] literal after `background-color:` (e.g. "black", "#fff0aa")
+    # @return [String] SVG with updated root background, or original on no-op / error
+    def self.apply_root_svg_background(svg_string, css_background)
+      return svg_string unless css_background.is_a?(String) && !css_background.empty?
+
+      svg_string.sub(
+        /(<svg\b[^>]+\bstyle="[^"]*?)background-color:\s*white;?/,
+        "\\1background-color: #{css_background};"
+      )
+    rescue StandardError
+      svg_string
+    end
+
+    def self.apply_edge_label_padding(svg_string, padding)
       svg_string.gsub(EDGE_LABEL_FOREIGN_OBJECT_RE) do
         prefix = Regexp.last_match(1)
         attrs = Regexp.last_match(2)

data/lib/jekyll-mermaid-prebuild/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JekyllMermaidPrebuild
-  VERSION = "0.4.0"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-mermaid-prebuild
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Texarkanine
@@ -29,6 +29,34 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: mutant
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+- !ruby/object:Gem::Dependency
+  name: mutant-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -105,28 +133,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.22'
+        version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.22'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: simplecov-cobertura
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: '4.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: '4.0'
 description: Jekyll plugin that converts mermaid diagram code blocks to SVG files
   at build time using the mmdc CLI. Eliminates the need for client-side mermaid.js
   (~2MB) by generating static SVG files with intelligent caching.