Updated Ruby Gem markdown_helper

Uncategorized

I’ve put up a new version of gem markdown_helper.

Now, by default, the output markdown has added comments that show:

* The path to the template file.
* The path to each included file.
* The image description (original) for each resolved image file path.

You can suppress those comments using the pristine option.

Advertisement

MarkdownHelper Updated

Documentation, github, markdown, opensource, Ruby gems

I have updated the markdown_helper gem.

Features:

  • File inclusion
  • mage path resolution (new)

The image path resolution replaces relative image paths with absolute image URLs.

  • This matters because in the documentation for a gem (on RubyDoc.info), YARD formatting changes some file structures, which breaks relative links to images.
  • The resolution to absolute URLs avoids that breakage.

More Help with Markdown?

Documentation, github, Ruby gems

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.