GitHub Markdown Tips

Burdette Lamar - Feb 7 '18 - - Dev Community

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