github/markup · error · LoadError

no suitable markdown gem found

Error message

no suitable markdown gem found

What it means

GitHub::Markup's Markdown implementation lazily picks a backend on first render: Markdown#load walks MARKDOWN_GEMS in order ('commonmarker', 'github/markdown', 'redcarpet', 'rdiscount', 'maruku', 'kramdown', 'bluecloth') and tries to require each. If every require raises LoadError, it raises LoadError 'no suitable markdown gem found'. In other words, the gem itself ships no Markdown renderer - exactly one of those gems must be in the load path (normally via your Gemfile) before any .md/.markdown/.mdx file is rendered.

Source

Thrown at lib/github/markup/markdown.rb:127

          BlueCloth.new(content).to_html
        },
      }

      def initialize
        super(
          /md|mkdn?|mdwn|mdown|markdown|mdx|litcoffee/i,
          ["Markdown", "MDX", "Literate CoffeeScript"])
      end

      def load
        return if @renderer
        MARKDOWN_GEMS.each do |gem_name, renderer|
          if try_require(gem_name)
            @renderer = renderer
            return
          end
        end
        raise LoadError, "no suitable markdown gem found"
      end

      def render(filename, content, options: {})
        load
        @renderer.call(content, options: options)
      end

      def name
        "markdown"
      end

    private
      def try_require(file)
        require file
        true
      rescue LoadError
        false
      end

View on GitHub (pinned to 76e2682193)

Solutions

1. Add a Markdown backend to the Gemfile - commonmarker is first choice: gem 'commonmarker', then run bundle install.
2. Verify the gem actually loads in the target environment: bundle exec ruby -e "require 'commonmarker'; puts 'ok'" from the deploy container.
3. Ensure the markdown gem is not in an excluded bundler group; check bundle config and Dockerfile for --without flags.
4. Call GitHub::Markup.preload! at boot so a missing backend fails fast at startup instead of on the first user-facing render.
5. As a stopgap only, rescue LoadError and fall back to escaping/presenting the raw Markdown text.

Example fix

# before
# Gemfile
gem 'github-markup'
# app
GitHub::Markup.render('doc.md', md)
# => LoadError: no suitable markdown gem found

# after
# Gemfile
gem 'github-markup'
gem 'commonmarker'
# then: bundle install && bundle exec ruby -e "require 'commonmarker'"
GitHub::Markup.render('doc.md', md) # renders HTML

# Fail fast at boot instead of on the first .md document:
def markdown_backend_available?
  %w[commonmarker github/markdown redcarpet rdiscount maruku kramdown bluecloth].any? do |g|
    require g
    true
  rescue LoadError
    false
  end
end

raise LoadError, 'no suitable markdown gem found - add commonmarker to the Gemfile' unless markdown_backend_available?

# Cheap presence probe for the preferred backend:
def commonmarker_loaded?
  defined?(Commonmarker) || (require 'commonmarker' && true)
rescue LoadError
  false
end

begin
  html = GitHub::Markup.render('doc.md', md)
rescue LoadError => e
  raise unless e.message == 'no suitable markdown gem found'
  # degrade deliberately: show source, alert ops that the backend is missing
  logger.error('markdown backend missing: add commonmarker to the Gemfile')
  html = "<pre>#{ERB::Util.html_escape(md)}</pre>"
end

When it happens

Trigger: Calling GitHub::Markup.render('README.md', content) or render_s(:markdown, content) when the bundle contains none of the supported markdown gems; calling GitHub::Markup.preload! in such a bundle; production deploys where the gem was added to a group (e.g. :development) that bundler excluded; a pruned Docker image where gems were vendor-installed without the markdown backend.

Common situations: Adding github-markup to a project and assuming Markdown works out of the box; bundle install --without on CI/prod skipping the group holding commonmarker; JRuby or platform builds where a native markdown gem failed to compile and was silently dropped; gems that wrap github-markup without declaring a hard dependency on any markdown backend.

Related errors

• unknown commonmarker option: #{opt.inspect}
• unknown commonmarker extension: #{ext.inspect}
• stderr
• Can not render a nil.
• The '#{symbol}' symbol is already defined.

AI-assisted analysis of github/markup@76e2682193 (2026-08-21). Data as JSON: /api/errors/0deae0ae37f48e11. Report an issue: GitHub.