I’ve added a proper command-line interface to gem markdown_helper.
I have put up gem markdown_helper v1.5, which supports nested include files. An included file can now include more files.
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.
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.
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.)
I have made public my GitHub repository MarkdownHelper.
The first feature is file inclusion for GitHub markdown, supporting included text as:
* Highlighted code block.
* Plain code block.
* Verbatim text.
I ran across this wonderful post by Richard Kim, largely about doing a better job on GitHub README.md files.
Changed my life. I’m doing major reworks.
Hey, Ruby coders!
Do you recognize this idiom?
Or this one?
When I wanted to do these two things in my RubyTest project, I had to Google to find out how.
Now if I put this code into my project, will I recognize these idioms later on? Next month? Next year?
I could add comments to explain, but a comment can get stale (not keep up with code changes), or get separated from its code, or even get deleted.
You can help your downstream code enhancer/maintainer by pushing an unusual idiom into a well-named method.
(Hint: If you’re not sure who is the downstream enhancer/maintainer, it’s you!)
Thus, I created this:
class ObjectHelper def self.get_class_for_class_name(class_name) Object::const_get(class_name) end def self.instantiate_class_for_class_name(class_name, *args) self.get_class_for_class_name(class_name).new(*args) end end
PS: My GitHub project is about test automation in Ruby. It has a Tester Tour of the demo testing for a web UI and for a REST API.