{"record":{"id":"0deae0ae37f48e11","repo":"github/markup","slug":"no-suitable-markdown-gem-found","errorCode":null,"errorMessage":"no suitable markdown gem found","messagePattern":"no suitable markdown gem found","errorType":"exception","errorClass":"LoadError","httpStatus":null,"severity":"error","filePath":"lib/github/markup/markdown.rb","lineNumber":127,"sourceCode":"          BlueCloth.new(content).to_html\n        },\n      }\n\n      def initialize\n        super(\n          /md|mkdn?|mdwn|mdown|markdown|mdx|litcoffee/i,\n          [\"Markdown\", \"MDX\", \"Literate CoffeeScript\"])\n      end\n\n      def load\n        return if @renderer\n        MARKDOWN_GEMS.each do |gem_name, renderer|\n          if try_require(gem_name)\n            @renderer = renderer\n            return\n          end\n        end\n        raise LoadError, \"no suitable markdown gem found\"\n      end\n\n      def render(filename, content, options: {})\n        load\n        @renderer.call(content, options: options)\n      end\n\n      def name\n        \"markdown\"\n      end\n\n    private\n      def try_require(file)\n        require file\n        true\n      rescue LoadError\n        false\n      end","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/github/markup/blob/76e2682193828b98471b3a071edf4db0590ccacb/lib/github/markup/markdown.rb#L109-L145","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add a Markdown backend to the Gemfile - commonmarker is first choice: gem 'commonmarker', then run bundle install.","Verify the gem actually loads in the target environment: bundle exec ruby -e \"require 'commonmarker'; puts 'ok'\" from the deploy container.","Ensure the markdown gem is not in an excluded bundler group; check bundle config and Dockerfile for --without flags.","Call GitHub::Markup.preload! at boot so a missing backend fails fast at startup instead of on the first user-facing render.","As a stopgap only, rescue LoadError and fall back to escaping/presenting the raw Markdown text."],"exampleFix":"# before\n# Gemfile\ngem 'github-markup'\n# app\nGitHub::Markup.render('doc.md', md)\n# => LoadError: no suitable markdown gem found\n\n# after\n# Gemfile\ngem 'github-markup'\ngem 'commonmarker'\n# then: bundle install && bundle exec ruby -e \"require 'commonmarker'\"\nGitHub::Markup.render('doc.md', md) # renders HTML","handlingStrategy":"validation","validationCode":"# Fail fast at boot instead of on the first .md document:\ndef markdown_backend_available?\n  %w[commonmarker github/markdown redcarpet rdiscount maruku kramdown bluecloth].any? do |g|\n    require g\n    true\n  rescue LoadError\n    false\n  end\nend\n\nraise LoadError, 'no suitable markdown gem found - add commonmarker to the Gemfile' unless markdown_backend_available?","typeGuard":"# Cheap presence probe for the preferred backend:\ndef commonmarker_loaded?\n  defined?(Commonmarker) || (require 'commonmarker' && true)\nrescue LoadError\n  false\nend","tryCatchPattern":"begin\n  html = GitHub::Markup.render('doc.md', md)\nrescue LoadError => e\n  raise unless e.message == 'no suitable markdown gem found'\n  # degrade deliberately: show source, alert ops that the backend is missing\n  logger.error('markdown backend missing: add commonmarker to the Gemfile')\n  html = \"<pre>#{ERB::Util.html_escape(md)}</pre>\"\nend","preventionTips":["Declare a markdown backend (gem 'commonmarker') next to gem 'github-markup' in the Gemfile - never rely on transitive availability.","Call GitHub::Markup.preload! during boot so missing backends crash the deploy, not a user request.","Verify in the production image, not just locally: bundle exec ruby -e \"require 'commonmarker'\" inside the deployed container.","Watch bundler group exclusions (--without / bundle config) - a markdown gem placed in an excluded group is invisible at runtime."],"tags":["missing-gem","markdown","bundler","dependency-resolution","ruby"],"backgroundTag":"missing-dependency","analyzedSha":"76e2682193828b98471b3a071edf4db0590ccacb","analyzedAt":"2026-08-21T19:16:29.859Z","schemaVersion":2},"datasetVersion":"2026-08-22T04:17:13.399Z"}