discourse_math_bundle

A Ruby gem that packages MathJax and KaTeX assets for the discourse-math plugin.

Why?

The discourse-math plugin needs MathJax and KaTeX JavaScript/CSS/font files to render mathematical notation. Rather than vendoring these large libraries directly in the plugin repository, this gem provides them as a dependency. This keeps the plugin lightweight and makes it easier to update math libraries independently.

Installation

Add to your Gemfile:

gem "discourse_math_bundle"

Usage

require "discourse_math_bundle"

# Get paths to asset directories
DiscourseMathBundle.mathjax_path  # => "/path/to/gem/vendor/assets/mathjax"
DiscourseMathBundle.katex_path    # => "/path/to/gem/vendor/assets/katex"

# Get version info
DiscourseMathBundle.mathjax_version  # => "4.1.0"
DiscourseMathBundle.katex_version    # => "0.16.27"

# Get detailed path information
paths = DiscourseMathBundle.paths
paths[:mathjax][:core]    # => path to core.js
paths[:katex][:js]        # => path to katex.min.js
paths[:katex][:css]       # => path to katex.min.css

Requirements

• Ruby >= 3.2
• pnpm >= 9

Project Layout

• lib/: gem entry point and version constants
• vendor/assets/: vendored MathJax and KaTeX bundles
• Rakefile: asset update, verification, and publish tasks

Development

Updating Assets

Refresh vendored assets from current npm versions:

bundle exec rake assets:update

Upgrade to latest npm package versions:

bundle exec rake assets:upgrade

This updates package.json, version constants in lib/discourse_math_bundle/version.rb, and copies fresh assets to vendor/assets/.

Verifying Assets

bundle exec rake assets:verify

Publishing

The gem is automatically published to RubyGems when changes are pushed to main. To release a new version:

1. Bump the VERSION constant in lib/discourse_math_bundle/version.rb
2. Commit and push to main
3. CI detects the version change and publishes to RubyGems

Manual publishing is also available via bundle exec rake gem:publish.

Notes

Do not edit files in vendor/assets/ by hand; always regenerate via Rake tasks.

License

MIT