Monthly Archives: February 2018


GitHub users have for years been asking for include files in GitHub markdown pages.

I’ve just put up a new Ruby gem, markdown_helper, that implements include files.

A file can be included as:

  • Highlighted code block.
  • Plain code block.
  • Verbatim text.

The gem has an API and a CLI. (For the very young, CLI == command-line interface.)

My GitHub Markdown Tips


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

A few of my own:

    • It’s not just
      • You can have any number of markdown pages.
      • They can be in any directories.
      • They can have filenames other than
      • 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:
      • 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:
      • 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:
      • If you link in a special way, the HTML will be rendered:
      • 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