Having README.md work for GitHub and Yard

[gam3]

I would like to use a different render than #html_markup_markdown uses by default.

Steps to reproduce

You see 2 different types of entries in README.md files

See {file:CHANGELOG.md} for a list of changes.

or

See the [CHANGELOG.md](CHANGELOG.md) file for details.

In the first case the link works for Yard but not for GitHub. In the second case it works for GitHub, but you get a file not found error in Yard.

The code below allows markdown links to be put in extra files and for the links to be fixed when Yard runs. However I find this rather inelegant and would prefer a better solution.

Any hints on how to proceed would be appreciated.

module YARD
  module Templates
    module Helpers
      module HtmlHelper # rubocop:disable Documentation
        # This class fixes up the \.md links in the extra files
        class MyRenderHTML < Redcarpet::Render::HTML
          def link(link, title, contents)
            if link.=~(/\.md$/)
              %(<a href="file.#{link.gsub(/\.md$/, '.html')}">#{contents}</a>)
            elsif title
              %(<a href="#{link}" title="#{title}"></a>)
            else
              %(<a href="#{link}">#{contents}</a>)
            end
          end
        end
        def html_markup_markdown(text)
          if @markdown.nil?
            # :no_intraemphasis, :gh_blockcode, :fenced_code, :autolink, :tables, :lax_spacing
            renderer = MyRenderHTML.new
            @markdown = Redcarpet::Markdown.new(renderer, :no_intra_emphasis => true, :gh_blockcode => true, :fenced_code_blocks => true, :autolink => true)
          end
          @markdown.render(text)
        end
      end
    end
  end
end

I have read the Contributing Guide.

[lsegal]

Don't override the renderer. Instead, create your own renderer and register it as a markup type:

https://github.com/lsegal/yard/blob/master/lib/yard/templates/helpers/markup_helper.rb#L25-L32

helper = YARD::Templates::Helpers::MarkupHelper
helper.clear_markup_cache
helper::MARKUP_PROVIDERS[:markdown].unshift const: 'MyMarkdown'

Markup classes just need to implement a constructor and .to_html methods:

class MyMarkdown
  attr_reader :to_html

  def initialize(text)
    renderer = MyRenderHTML.new
    markdown = Redcarpet::Markdown.new(renderer, no_intra_emphasis: true, ...)
    @to_html = markdown.render(text)
  end
end

Hope that helps.

[lsegal]

I just edited the above snippet (registering the provider) to be more accurate. Previous snippet would not work correctly. Also simplified the markdown provider implementation.

[lsegal]

Marking this as closed since the above should answer the question. Feel free to re-open if you have others.

[keithharvey]

@lsegal Hey, it's not clear to me where the best place to bootstrap this is?

helper = YARD::Templates::Helpers::MarkupHelper
helper.clear_markup_cache
helper::MARKUP_PROVIDERS[:markdown].unshift const: 'MyMarkdown'

I was hoping to do something similar to this.

[machty]

@keithharvey did you ever figure it out? It's not clear from the docs where to "hook in" or "bootstrap" custom overrides in Ruby like this.

[machty]

The only thing I've come up with that seems to work in all contexts is defining an unpublished yard-my-custom-overrides gem in my apps lib directory and using a .yardopts file with --plugin my-custom-overrides. Is there an easier way? In particular, the solution needs to work for both:

1. Building the yard docs statically
2. Running the yard server