More Help with Markdown?

Ruby Chat
1

The markdown_helper gem I’ve put up does (so far) one thing:

  • Supports file inclusion.

I have in mind two additional features:

  • Support for relative links for images (see below for why this matters).
  • Support slideshow-style markdown pages (pages linked by next/prev navigation links).

Query: What else would be useful?

About relative links for images: they work fine in GitHub markdown, but when the project is formed into a gem, the links are broken in the gem’s documentation. That’s because on RubyDoc.info, YARD has rearranged some files and folders.

The workaround is to substitute absolute links to the files in raw.githubusercontent.com. This would be very inconvenient, not to say tedious and possibly error-prone.

What I want to add to the helper is a method that replaces the relative links with absolute ones automatically. That way, we have the convenience of relative links on GitHub, and correct (absolute) links on RubyDoc.

2

Here are some regexs that may help.

MARKDOWN_LINK = Regexp.new(/\[[\w\s]+\]\([\/\S]{1,}\)/)
MARKDOWN_LINK === "[a sdf](/asdf)"
# => true

HTTP_IN_LINK = Regexp.new(/\[.+\]\(http.+\)/)
HTTP_IN_LINK === "[a sdf](http://example.com)"
# => true
HTTP_IN_LINK === "[a sdf](example.com)"
# => false

ROOT_DOMAIN = Regexp.new(/\[.+\]\(.+\.(?:co|com|org|net)(?:\S+)?\)/)
ROOT_DOMAIN === "[a sdf](http://example.com)"
# => true
ROOT_DOMAIN === "[a sdf](example.com)"
# => true
ROOT_DOMAIN === "[a sdf](example.cpp)"
# => false

The ROOT_DOMAIN would need more work to fit your criteria. The main thing would be to match existing domain extensions and not file name extensions.

Once you have something that matches your criteria you can do an in place substitution.

"[a sdf](asdf)".gsub(/\((?<rel_path>\S+)\)/, '(https::/github.com/username/repository/\k<rel_path>)')
# => "[a sdf](https::/github.com/username/repository/asdf)"

You may have to gsub on a line twice, once from the URL match to generate a new one, and then again on the original line to replace the match with the URL.

This is likely how I would do it if I were to write it from scratch. The more general the use case the easier it is to make (as in the less domains to worry about and such).

This would be much simpler if the markdown could be loaded in as a web DOM as there are many tools geared around that technology.