Module: YARD::RelativeMarkdownLinks

Defined in:
lib/yard/relative_markdown_links.rb,
lib/yard/relative_markdown_links/version.rb

Overview

GitHub and YARD render Markdown files differently. In particular, relative links between Markdown files that work in GitHub don’t work in YARD. For example, if you have [hello](FOO.md) in your README, YARD renders it as <a href="FOO.md">hello</a>, creating a broken link in your docs.

With this plugin enabled, you’ll get <a href="file.FOO.html">hello</a> instead, which correctly links through to the rendered HTML file.

Constant Summary collapse

VERSION =

Current version of the yard-relative_markdown_links gem.

"0.5.0"

Instance Method Summary collapse

Instance Method Details

Resolves relative links from Markdown files.

Parameters:

  • text (String) —

    the HTML fragment in which to resolve links.

Returns:

  • (String) —

    HTML with relative links to extra files converted to {file:} links.



21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
 
# File 'lib/yard/relative_markdown_links.rb', line 21

def resolve_links(text)
  return super unless options.files

  filenames = options.files.to_set(&:filename)

  rdoc_filenames = filenames.filter_map { |filename|
    # https://github.com/ruby/rdoc/blob/0e060c69f51ec4a877e5cde69b31d47eaeb2a2b9/lib/rdoc/markup/to_html.rb#L364-L366
    match = %r{\A(?<dirname>(?:[^/#]*/)*+)(?<basename>[^/#]+)\.(?<ext>rb|rdoc|md)\z}i.match(filename)
    next unless match

    ["#{match[:dirname]}#{match[:basename].tr('.', '_')}_#{match[:ext]}.html", filename]
  }.to_h

  html = Nokogiri::HTML.fragment(text)

  html.css("a[href]").each do |link|
    href = URI(link["href"])
    next unless href.relative?

    if filenames.include?(href.path)
      link.replace "{file:#{href} #{link.inner_html}}"
      next
    end

    href.path = rdoc_filenames[href.path]
    next unless href.path && filenames.include?(href.path)

    link.replace "{file:#{href} #{link.inner_html}}"
  end

  super(html.to_s)
end