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.