Have YARD render markdown files with GFM (Github Flavored Markdown)

.yard_support.rb

@@ -0,0 +1,21 @@
+require 'kramdown'
+require 'kramdown-parser-gfm'
+
+# Custom markup provider class that always renders Kramdown using GFM (Github Flavored Markdown).
+# GFM is needed to render markdown tables and fenced code blocks in the README.
+class KramdownGfmDocument < Kramdown::Document
+  def initialize(source, options = {})
+    options[:input] = 'GFM' unless options.key?(:input)
+    super(source, options)
+  end
+end
+
+# Insert the new provider as the highest priority option for Markdown.
+# See:
+# - https://github.com/lsegal/yard/issues/1157
+# - https://github.com/lsegal/yard/issues/1017
+# - https://github.com/lsegal/yard/blob/main/lib/yard/templates/helpers/markup_helper.rb
+YARD::Templates::Helpers::MarkupHelper::MARKUP_PROVIDERS[:markdown].insert(
+  0,
+  { const: 'KramdownGfmDocument' }
+)

.yardopts

@@ -0,0 +1 @@
+--load .yard_support.rb

Gemfile.lock

@@ -201,6 +201,8 @@ DEPENDENCIES
   gem-release
   github_changelog_generator
   good_job!
+  kramdown
+  kramdown-parser-gfm
   mdl
   pry-rails
   puma

README.md

@@ -11,7 +11,7 @@ GoodJob is a multithreaded, Postgres-based, ActiveJob backend for Ruby on Rails.
 
 For more of the story of GoodJob, read the [introductory blog post](https://island94.org/2020/07/introducing-goodjob-1-0).
 
-<details>
+<details markdown="1">
 <summary><strong>📊 Comparison of GoodJob with other job queue backends (click to expand)</strong></summary>
 
 |                 | Queues, priority, retries | Database                              | Concurrency       | Reliability/Integrity  | Latency                  |

good_job.gemspec

@@ -50,6 +50,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "foreman"
   spec.add_development_dependency "gem-release"
   spec.add_development_dependency "github_changelog_generator"
+  spec.add_development_dependency "kramdown"
+  spec.add_development_dependency "kramdown-parser-gfm"
   spec.add_development_dependency "mdl"
   spec.add_development_dependency "pry-rails"
   spec.add_development_dependency "puma"