Updated Ruby Gem markdown_helper

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.


MarkdownHelper Updated

I have updated the markdown_helper gem.


  • 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?

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.

My GitHub Markdown Tips


I posted earlier about Richard Kim’s blog post that has some great tips for building an effective README.md page on GitHub.

A few of my own:

    • It’s not just README.md:
      • You can have any number of markdown pages.
      • They can be in any directories.
      • They can have filenames other than README.md.
      • The only ‘requirement’ is that for GH to render a markdown page properly, it must have the .md file extension.
    • You can link to a page with a normal GitHub URL:
      • https://github.com/user/project/blob/branch/file.md.
      • This lands readers at the top of the page, where they see various project information. (The actual markdown text will be farther down the page.)
    • You can link to a title in the markdown on a page with an extended URL:
      • https://github.com/user/project/blob/branch/file.md#title.
      • This lands the browser (Firefox at least) exactly at the title, not at the top of the page. (Get the exact URL from title’s link icon.)
      • The target title can be any title on the page (not just the main one, identified with a single #.)
    • This is especially useful for linking among markdown pages, so that the reader lands in the markdown text, instead of at the top of the page.
    • I’ve done this with my project’s Tester Tour, where each page in the tour has navigation links, forward and backward.
    • I have a MarkdownHelper class that I use to:
      • Build the tour by adding the navigation links.
      • Include external files by inlining them.
      • Add text highlighting if the file is .rb or .xml. (This can be extended to any language known to GitHub).
      • Query: Should this class be made into a Ruby gem?


    • Linking from markdown to an HTML file:
      • If you link in the usual way, the HTML will not be rendered: https://github.com/user/project/blob/branch/file.html
      • If you link in a special way, the HTML will be rendered: https://htmlpreview.github.io/?https://github.com/user/project/file.html
      • I would illustrate, but from here opening either type of link causes the HTML to be rendered. The difference is seen only in GitHub markdown.
      • But you can see it work via the link at the foot of https://github.com/BurdetteLamar/RubyTest/blob/master/examples/changes_report/ChangesReport.md.

Comes Now, DebugHelper

I have no idea how many times I’ve typed code like this (to do printf-style debugging):

my_hash.each_pair do |key, value|
  p [key, value]

I’ve finally wised up, and built a helper method to support this:


The method allows any data, and specifically supports Hash-like and Array-like structures.

It also allows an optional name (defaults to data class-name) and message.

Typical outputs:

Hash (size=3)
  a => 0
  b => 1
  c => 2

Array (size=3)
  0: a
  1: b
  2: c

And here’s my helper class:

# Class to help in 'printf' debugging.
class DebugHelper
  def self.printf(data, name = data.class.to_s, description = '')
    size = data.respond_to?(:size) ? data.size : 1
    puts format('%s (size=%d) %s', name, size, description)
      when data.respond_to?(:each_pair)
        # Hash-like.
        data.each_pair do |k, v|
          puts format('  %s => %s', k, v)
      when data.respond_to?(:each_with_index)
        # Array-like or Set-like.
        data.each_with_index do |v, i|
          puts format('  %6d: %s', i, v)
        puts format('  %s', data.inspect)

Test Automation Sherpa

“Test Automation Professional / Zealot” is the title I have in my resume.

But I’m not a tester, and still less a “quality” engineer.

Then what am I?

To borrow from mountain-climbing vocabulary, I’m not a climber, I’m a sherpa — one who does much of the heavy lifting, creates base camps, and keeps the climbers progressing happily and safely.

In that spirit, I aim to make it possible for others to do automated testing easily and reliably.

For a year now I’ve worked on my GitHub project, RubyTest, which embodies what I’ve learned in long years of building test automation.

It includes:

  • Core (application-independent) support:
    • Base classes
    • Helper classes
    • Logging
    • Reporting
  • Unit testing for the core (of course!).
  • Example domain-specific code:
    • Page objects, for web UI testing.
    • Endpoint objects, for TEST API testing.
    • Data objects, for both types of testing.
  • Example domain-specific tests.

Most recently, I’ve been building a Tester Tour of part of the project — the part that demonstrates testing for a REST API and a web UI. (The demo test targets are GitHub’s own REST API and web UI.)


You can see the tour here.

Any feedback appreciated, either as Issues on GH, comments here, or private email.