GitHub Markdown Tips

#opensource #learning #github #markdown

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.