Class: Yard::Fence::KramdownGfmDocument

Inherits:
Kramdown::Document
  • Object
show all
Defined in:
lib/yard/fence/kramdown_gfm_document.rb

Constant Summary collapse

UNRENDERED_FENCE_PARAGRAPH =

Detects an unrendered fenced code block that slipped through HTML generation. Note on <details markdown=“1”>:

  • The classic kramdown parser honors the markdown=“1” attribute on block HTML like <details>, and will parse contained markdown as block-level content.

  • The GFM parser generally handles many cases well, and markdown=“1” may appear to work in most sections; however, we’ve observed edge cases where fenced code blocks inside a <details markdown=“1”> are left as literal backticks (rendered as <p>“‘ …</p>). This fallback detects that situation and re-renders with the classic parser.

/<p>```/
DETAILS_MARKDOWN_1 = 
/<details[^>]*markdown=["']1["'][^>]*>/i

Instance Method Summary collapse

Constructor Details

#initialize(source, options = {}) ⇒ KramdownGfmDocument

Returns a new instance of KramdownGfmDocument.



26
27
28
29
30
 
# File 'lib/yard/fence/kramdown_gfm_document.rb', line 26

def initialize(source, options = {})
  options[:input] = "GFM" unless options.key?(:input)
  @__yard_fence_source = source # Keep original for potential fallback.
  super(source, options)
end

Instance Method Details

#to_html ⇒ Object

Override to_html to provide a smart fallback: if the GFM parse leaves literal fenced code markers (“‘), re-run the render with the classic ’kramdown’ input which correctly evaluates markdown inside <details markdown=“1”> blocks. Opt-out via ENV == “1”.



36
37
38
39
40
41
42
43
44
45
46
47
 
# File 'lib/yard/fence/kramdown_gfm_document.rb', line 36

def to_html
  html = super
  return html if ENV["YARD_FENCE_DISABLE_FALLBACK"] == "1"
  return html unless @__yard_fence_source.include?("```")

  if needs_fallback?(html)
    fallback_options = @options.merge(input: "kramdown")
    fb_html = Kramdown::Document.new(@__yard_fence_source, fallback_options).to_html
    return fb_html if fallback_improved?(fb_html)
  end
  html
end