Local documentation is ugly about active_interaction HOT 1 CLOSED

It just occurred to me why everything looks fine on RubyDoc.info: they're using RedCarpet. We could use RedCarpet in MRI and kramdown in JRuby, but that's definitely a hack:

if RUBY_PLATFORM == 'java'
  spec.add_development_dependency 'kramdown'
else
  spec.add_development_dependency 'redcarpet'
end

(We'd also have to remove --markup-provider=kramdown from .yardopts. It'll just use whatever's available.)

I surveyed YARD's Markdown providers. BlueCloth, RDiscount, RedCarpet, and Ruby PEG Markdown all use C libraries behind the scenes, so they're out. That leaves kramdown, Maruku, and RDoc. Maruku doesn't support either fenced code block syntax, so it's out. RDoc appears to work reasonably well with the following caveats:

• It doesn't support tilde-fenced code blocks.
• It shows the badges as text links, which isn't a big deal for local documentation. ("Image links are not generated correctly")
• Code blocks are syntax highlighted in JRuby, but they lose indentation.

So between kramdown and RDoc, I think RDoc is the winner.

from active_interaction.