Jekyll SVG Viewer

A sophisticated WordPress plugin for displaying large SVG diagrams with panning, scroll, and text searchability.

jekyll-svg-viewer brings the BT SVG Viewer frontend to static Jekyll sites. It ships a Liquid tag for rendering interactive SVG diagrams, automatically injects the required JavaScript/CSS, mirrors the shortcode options from the WordPress plugin, and includes a standalone preset builder page for crafting configurations. Source code lives at github.com/ttscoff/jekyll-svg-viewer.

Installation

  1. Add the published gem to your Jekyll site:

    # Gemfile
gem "jekyll-svg-viewer"

    Need the latest unreleased changes? Point Bundler at GitHub instead:

    gem "jekyll-svg-viewer", github: "ttscoff/jekyll-svg-viewer"

  2. Enable the plugin:

    # _config.yml
plugins:
  - jekyll-svg-viewer

  3. Run bundle install, then build or serve your site as usual (bundle exec jekyll build / bundle exec jekyll serve). The viewer assets are copied into _site/assets/svg-viewer/ as part of the build.

Liquid Tag Usage

Place the svg_viewer tag anywhere Liquid tags are supported:

{% svg_viewer src="/assets/maps/campus.svg" height="75vh" controls_buttons="compact,alignright,zoom_in,zoom_out,center" zoom="140" %}

All shortcode options from the WordPress version are supported. Common attributes include:

Attribute Purpose
src Required. Absolute URL or site-root relative path to the SVG.
height Viewer height (e.g. 600px, 80vh).
zoom, min_zoom, max_zoom, zoom_step Initial zoom, min/max bounds, and button increment (percentages).
center_x, center_y Lock the default viewport to explicit SVG coordinates.
show_coords true enables the coordinate helper button.
controls_position top, bottom, left, or right.
controls_buttons Comma-delimited layout keywords and button names (e.g. both,alignleft,zoom_in,reset).
button_fill, button_border, button_foreground Hex colors mapped to CSS custom properties for the buttons.
pan_mode, zoom_mode Advanced gesture overrides (scroll, drag, click).
title, caption Optional markup rendered above/below the viewer wrapper.

Any attribute omitted from the tag falls back to _config.yml defaults (see below).

Site-wide Defaults

Configure default values in _config.yml under svg_viewer.defaults. The builder’s YAML modal emits the same structure.

svg_viewer:
  defaults:
    height: "600px"
    zoom: "100"
    min_zoom: "25"
    max_zoom: "800"
    zoom_step: "10"
    controls_position: "top"
    controls_buttons: "both"
    pan_mode: ""
    zoom_mode: ""
    show_coords: false

Only fields you override are required. src, center_x, and center_y remain per-tag settings.

Screenshots

Preset Editor
SVG Viewer Front End

Localized Assets & Automatic Injection

The gem copies the viewer script, stylesheet, and localization JSON into _site/assets/svg-viewer/. Whenever a page renders {% svg_viewer %}, the plugin:

  • Marks the document so the CSS/JS tags are injected into <head> once during post_render.
  • Ensures the asset files exist by the post_write phase.

You don’t need to manually edit layouts or partials—the assets appear only on pages that use the tag.

Preset Builder Page

The plugin also generates a preset editor at /svg-viewer/preset-builder/. It mirrors the WordPress admin experience:

  • Enter an SVG path, tweak zoom/controls/colors, and load a live preview.
  • Capture the current viewport to populate center_x / center_y.
  • Copy a ready-to-use Liquid tag.
  • Generate a _config.yml snippet (excluding src and the captured center) inside a modal dialog.

This is the quickest way to dial in viewer options without memorizing every attribute.

Development Notes

  • The gemspec bundles the compiled frontend assets. If you update wp-svg-viewer/js/svg-viewer.js or related CSS, re-copy them into jekyll-svg-viewer/assets/svg-viewer/.
  • The preset builder JavaScript (assets/svg-viewer/preview/preset-builder.js) is framework-free and mirrors the PHP logic used by the WordPress plugin.
  • A minimal smoke-test site is available in example_site/. Run scripts/build-example.sh to install dependencies and build it locally.

License

MIT © Brett Terpstra

Changelog

Click to expand

404: Not Found

Speaking of Jekyll SVG Viewer…

Related Projects