jazzy 0.15.4 fails at startup with mustache 1.1.3: `undefined method 'map' for an instance of Pathname`

Since mustache 1.1.3 was published (2026-08-20), every jazzy invocation aborts before doing any work. jazzy's dependency is mustache (~> 1.1), so a fresh bundle install or bundle update picks the new version up with no change on the jazzy side.

Filing this mostly so it is findable by others hitting the same wall — we are just users of jazzy, so please take the analysis below as a report rather than a diagnosis of what jazzy should do.

Symptom

$ jazzy --config .jazzy.yaml --theme fullwidth --output <dir>
.../mustache-1.1.3/lib/mustache/settings.rb:47:in 'setup_path': undefined method 'map' for an instance of Pathname (NoMethodError)

    path.map{|p| File.expand_path(p)}
        ^^^^
Did you mean?  tap
	from .../mustache-1.1.3/lib/mustache/settings.rb:55:in 'template_path='
	from .../jazzy-0.15.4/lib/jazzy/config.rb:546:in 'theme_directory='
	from .../jazzy-0.15.4/lib/jazzy/config.rb:34:in 'call'
	from .../jazzy-0.15.4/lib/jazzy/config.rb:34:in 'set_raw'
	from .../jazzy-0.15.4/lib/jazzy/config.rb:38:in 'set'
	from .../jazzy-0.15.4/lib/jazzy/config.rb:43:in 'set_to_default'
	from .../jazzy-0.15.4/lib/jazzy/config.rb:540:in 'block in initialize'
	from .../jazzy-0.15.4/lib/jazzy/config.rb:539:in 'each'
	from .../jazzy-0.15.4/lib/jazzy/config.rb:539:in 'initialize'
	from .../jazzy-0.15.4/lib/jazzy/config.rb:550:in 'new'
	from .../jazzy-0.15.4/lib/jazzy/config.rb:550:in 'parse!'
	from .../jazzy-0.15.4/bin/jazzy:16:in '<top (required)>'

It fires from set_to_default during Config#initialize, so as far as we can tell it is independent of the config file, the theme and the sources — any invocation reaching Config.parse! seems to hit it.

What we found while tracing it

lib/jazzy/config.rb:

def theme_directory=(theme_directory)
  @theme_directory = theme_directory
  Doc.template_path = theme_directory + 'templates'
end

theme_directory is a Pathname, and Pathname + String yields a Pathname, so mustache's template_path= receives a Pathname.

That worked against mustache 1.1.2, whose setter was @template_path = File.expand_path(path) — and File.expand_path accepts any object implementing to_path. 1.1.3 replaced it with a setup_path helper that branches only on String and then calls .map, so a Pathname no longer gets through.

Our reading is that the breaking change is on the mustache side, in a patch release. We reported it there with the bisect and a possible patch: mustache/mustache#293 (open since 2026-08-20, no maintainer response yet). We have no idea how responsive that project is, which is the only reason we are also mentioning it here rather than just waiting.

Ideas, for whatever they are worth

We are not familiar enough with jazzy's internals to know which of these fits, or whether the right answer is simply to wait for mustache:

• Passing a String — (theme_directory + 'templates').to_s — makes it work under both 1.1.2 and 1.1.3 in our testing, and does not depend on upstream acting. We do not know whether jazzy relies on Doc.template_path staying a Pathname elsewhere, which would make this less trivial than it looks.
• Constraining the gemspec dependency away from 1.1.3 would stop existing installs resolving to the broken version, at the cost of a release.
• One thing worth being aware of either way: 1.1.3 also changed template_file to return nil instead of a String when no candidate file is readable, and added a context_access_security_level setting defaulting to 2 that blacklists reflection-related methods in context lookups. If jazzy touches either, moving to 1.1.3 may need more than the template_path call site.

Happy to test a patch against our setup if that would help, or to leave this with you entirely.

Workaround for anyone else landing here

Pinning in your own Gemfile is enough until a fixed jazzy or mustache ships:

gem 'mustache', '< 1.1.3'

Environment

• jazzy 0.15.4 (current release, 2025-10-20)
• mustache 1.1.3 (2026-08-20); last good 1.1.2 (2026-02-24)
• Ruby 3.3.10 and 3.3.11, macOS
• Not theme-specific as far as we could tell