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.
Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s