jekyll-mermaid-prebuild 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0f97de5928066d6b512188d2aba57a8762048d1158f70fcaa256ace7fc7e662
-  data.tar.gz: 4cb3056e57fa86d73e2a9ff0d12336fa8edda8fa7c3fa3aeddbc51506b6ffd3d
+  metadata.gz: 774a2f269fa0af19b0e9dd2008518271984d1a3e812037fa0eb9c27d54b08ed9
+  data.tar.gz: ce18c8d08f2fb59ebbffdd02c87e32dccd021bb839650aebbc065fa5778cae0e
 SHA512:
-  metadata.gz: dd4085acef77b82dfc0f261a70c018be7de076362b3f9b31b1aa480c4503143d73798ff79fb9f978a6442ea2d45e505f89680b47e59a403e3ce9bae8b1e2bca3
-  data.tar.gz: b9e4d6ce68bb02d9e144f290cee07466ce0411bef61be91469570d330e8f260ae945e2ddb8c5de11321201b8bd74fedb03847ffa626bdafcb2d03bdc0516256e
+  metadata.gz: bb13f85293b01d89745391543a28885ecc3ff05a9ca4448c5c8929df641cb72801c2efc65c6984d9960b36cea1a92716adeb6c3b66bc12d19013b6b23750dbd4
+  data.tar.gz: cec8771614670a55c05b0690db77d6914952a5354362aa402296d96caea841ee3647f4a3c64d39145e18bf0cb45bc6d6d82d0c52696a679c5e8e9b1ca4747a7f

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.3.2](https://github.com/Texarkanine/jekyll-mermaid-prebuild/compare/v0.3.1...v0.3.2) (2026-03-22)
+
+
+### Bug Fixes
+
+* block diagram node label centering and clipping w/ latest Mermaid ([#16](https://github.com/Texarkanine/jekyll-mermaid-prebuild/issues/16)) ([ae250c1](https://github.com/Texarkanine/jekyll-mermaid-prebuild/commit/ae250c14fd04d3f1826a70b8af339ced67bb988a))
+
+## [Unreleased]
+
+### Features
+
+* Optional `block_edge_label_padding` widens block-diagram edge-label `<foreignObject>` widths after mmdc to prevent clipping caused by cross-browser text measurement differences on non-Mac build hosts.
+
+### Bug Fixes
+
+* Inject `foreignObject > div { display: block !important; text-align: center }` into every generated SVG so that label text centers correctly when the viewing browser's font metrics differ from the generating headless Chromium. Fixes left-shifted labels visible when mmdc runs on a different OS than the viewer.
+
 ## [0.3.1](https://github.com/Texarkanine/jekyll-mermaid-prebuild/compare/v0.3.0...v0.3.1) (2026-03-13)
 
 

data/README.md

@@ -94,6 +94,7 @@ Add to your `_config.yml`:
 mermaid_prebuild:
   enabled: true          # default: true
   output_dir: assets/svg # default: assets/svg
+  block_edge_label_padding: 0   # optional; see Block diagrams below
   emoji_width_compensation:  # optional, see below
     flowchart: true
 ```
@@ -104,8 +105,23 @@ mermaid_prebuild:
 |--------|---------|-------------|
 | `enabled` | `true` | Enable/disable the plugin |
 | `output_dir` | `assets/svg` | Directory for generated SVG files |
+| `block_edge_label_padding` | `0` | Extra SVG user units added to **block** diagram edge-label `<foreignObject>` widths after mmdc (off when `0`, `false`, or omitted). 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. |
 
+### 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 applies two automatic fixes to every generated SVG:
+
+1. **Text centering** (always on, no config needed): Mermaid's CSS sets `text-align: center` on SVG `<g>` elements, but that has no effect on HTML inside `<foreignObject>`. The plugin injects a CSS rule (`foreignObject > div { display: block !important; text-align: center }`) so that label text centers within its container regardless of font metric differences. This is idempotent — if upstream Mermaid fixes this, the rule becomes redundant but harmless.
+
+2. **Block edge label padding** (opt-in via `block_edge_label_padding`): Block diagram edge labels have zero padding between the `<foreignObject>` boundary and the text. If the viewing browser renders text wider than headless Chromium measured, the last character(s) clip. This option widens only **edge** label `<foreignObject>` elements (not node labels) in SVGs whose root has `aria-roledescription="block"`. Flowcharts and other diagram types are unchanged.
+
+   - **When to enable:** If block diagram edge text clips in generated SVGs on your build host.
+   - **Starting value:** Try `4`-`8` (SVG user units); increase only if needed.
+   - **Caching:** The cache key includes this padding for block diagrams only, so changing the value invalidates cached block SVGs without affecting flowcharts.
+
+> **CI tip:** If your CI pipeline sets `PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true` and `PUPPETEER_EXECUTABLE_PATH` to the runner's system Chrome, remove those overrides. Puppeteer's bundled Chromium produces measurements closer to common viewing browsers than the GitHub Actions runner's system Chrome, which can measure text 10-16% narrower.
+
 ### Emoji width compensation
 
 Headless Chromium (used by mermaid-cli/mmdc) [undermeasures emoji glyph widths](https://stackoverflow.com/q/42016125) on non-Mac platforms. That can make node labels containing emoji clip in the generated SVG. This option tells the plugin to **append invisible `&nbsp;` padding** to emoji-containing node labels *before* passing the source to mmdc, so Puppeteer allocates correct widths.
@@ -144,12 +160,13 @@ mermaid_prebuild:
 
 ## Caching
 
-Generated SVGs are cached in `.jekyll-cache/jekyll-mermaid-prebuild/`. The cache key is based on the diagram content (and, when emoji compensation is enabled for that diagram type, the compensated source), so:
+Generated SVGs are cached in `.jekyll-cache/jekyll-mermaid-prebuild/`. The cache key is based on the diagram content (and, when emoji compensation is enabled for that diagram type, the compensated source; when `block_edge_label_padding` is positive, block diagrams also mix in that value), so:
 
 - Unchanged diagrams are served from cache (fast rebuilds)
 - 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 `block_edge_label_padding` invalidates cache keys for **block** diagrams only
 
 To clear the cache:
 

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

@@ -6,7 +6,7 @@ module JekyllMermaidPrebuild
     DEFAULT_OUTPUT_DIR = "assets/svg"
     CACHE_DIR = ".jekyll-cache/jekyll-mermaid-prebuild"
 
-    attr_reader :output_dir, :emoji_width_compensation
+    attr_reader :output_dir, :emoji_width_compensation, :block_edge_label_padding
 
     # Initialize configuration from Jekyll site
     #
@@ -16,6 +16,7 @@ module JekyllMermaidPrebuild
       @output_dir = parse_output_dir(config["output_dir"])
       @enabled = config.fetch("enabled", true)
       @emoji_width_compensation = parse_emoji_width_compensation(config["emoji_width_compensation"])
+      @block_edge_label_padding = parse_block_edge_label_padding(config["block_edge_label_padding"])
     end
 
     # Check if the plugin is enabled
@@ -54,5 +55,16 @@ module JekyllMermaidPrebuild
       # Strip leading/trailing slashes for consistency
       dir.gsub(%r{^/+|/+$}, "")
     end
+
+    # @param value [Object] raw config (numeric or off)
+    # @return [Numeric] non-negative padding in SVG user units; 0 means disabled
+    def parse_block_edge_label_padding(value)
+      return 0 if value.nil? || value == false
+
+      num = value.is_a?(Numeric) ? value : nil
+      return 0 unless num
+
+      num.negative? ? 0 : num
+    end
   end
 end

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

@@ -18,8 +18,9 @@ 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)
+    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
@@ -32,6 +33,8 @@ module JekyllMermaidPrebuild
       success = MmdcWrapper.render(mermaid_source, cache_path)
       return nil unless success
 
+      post_process_svg(cache_path, diagram_type)
+
       cache_path
     end
 
@@ -54,5 +57,17 @@ module JekyllMermaidPrebuild
         </figure>
       HTML
     end
+
+    private
+
+    def post_process_svg(cache_path, diagram_type)
+      raw = File.read(cache_path)
+      svg = SvgPostProcessor.ensure_text_centering(raw)
+
+      pad = @config.block_edge_label_padding
+      svg = SvgPostProcessor.apply(svg, padding: pad) if diagram_type == "block" && pad.is_a?(Numeric) && pad.positive?
+
+      File.write(cache_path, svg) if svg != raw
+    end
   end
 end

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

@@ -46,6 +46,16 @@ module JekyllMermaidPrebuild
 
     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)
+      pad = @config.block_edge_label_padding
+      return "#{source}\0block_edge_pad=#{pad}" if diagram_type == "block" && pad.is_a?(Numeric) && pad.positive?
+
+      source
+    end
+
     # Convert a single mermaid block to SVG
     #
     # @param block [Hash] block info with :content key
@@ -58,8 +68,9 @@ module JekyllMermaidPrebuild
                           else
                             mermaid_source
                           end
-      cache_key = DigestCalculator.content_digest(source_for_render)
-      cached_path = @generator.generate(source_for_render, cache_key)
+      digest_input = digest_string_for_cache(source_for_render, diagram_type)
+      cache_key = DigestCalculator.content_digest(digest_input)
+      cached_path = @generator.generate(source_for_render, cache_key, diagram_type: diagram_type)
 
       return nil unless cached_path
 

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module JekyllMermaidPrebuild
+  # Post-processes mmdc-generated SVGs to fix cross-browser rendering issues.
+  #
+  # Two 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
+  #    and viewing browsers. Always applied, idempotent.
+  # 2. Block edge label padding: Widens block-diagram edge-label `<foreignObject>` widths to
+  #    prevent clipping when the viewing browser renders text wider than headless Chromium measured.
+  #    Opt-in via `block_edge_label_padding` config.
+  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)
+      (\s[^>]+)
+      (>)
+    /x
+
+    BLOCK_ROOT_MARKER = 'aria-roledescription="block"'
+
+    # @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?
+      return svg_string unless svg_string.include?(BLOCK_ROOT_MARKER)
+
+      apply_edge_label_padding(svg_string, padding)
+    rescue StandardError
+      svg_string
+    end
+
+    CENTERING_RULE = "foreignObject > div{display:block !important;text-align:center;}"
+
+    # Injects a CSS rule into the SVG <style> block that centers text inside foreignObject divs.
+    # Mermaid's own `.node .label { text-align: center }` targets SVG <g> elements where
+    # text-align has no effect; this rule targets the HTML div directly.
+    # Idempotent: no visual effect when foreignObject width matches text width.
+    #
+    # @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)
+      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)
+      svg_string.gsub(EDGE_LABEL_FOREIGN_OBJECT_RE) do
+        prefix = Regexp.last_match(1)
+        attrs = Regexp.last_match(2)
+        suffix = Regexp.last_match(3)
+        new_attrs = attrs.sub(/\swidth="(\d+(?:\.\d+)?)"/) do
+          new_w = Regexp.last_match(1).to_f + padding
+          %( width="#{format("%g", new_w)}")
+        end
+        prefix + new_attrs + suffix
+      end
+    end
+    private_class_method :apply_edge_label_padding
+  end
+end

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

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

data/lib/jekyll-mermaid-prebuild.rb

@@ -6,6 +6,7 @@ require_relative "jekyll-mermaid-prebuild/version"
 require_relative "jekyll-mermaid-prebuild/configuration"
 require_relative "jekyll-mermaid-prebuild/digest_calculator"
 require_relative "jekyll-mermaid-prebuild/emoji_compensator"
+require_relative "jekyll-mermaid-prebuild/svg_post_processor"
 require_relative "jekyll-mermaid-prebuild/mmdc_wrapper"
 require_relative "jekyll-mermaid-prebuild/generator"
 require_relative "jekyll-mermaid-prebuild/processor"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-mermaid-prebuild
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Texarkanine
@@ -147,6 +147,7 @@ files:
 - lib/jekyll-mermaid-prebuild/hooks.rb
 - lib/jekyll-mermaid-prebuild/mmdc_wrapper.rb
 - lib/jekyll-mermaid-prebuild/processor.rb
+- lib/jekyll-mermaid-prebuild/svg_post_processor.rb
 - lib/jekyll-mermaid-prebuild/version.rb
 homepage: https://github.com/Texarkanine/jekyll-mermaid-prebuild
 licenses: