I’ve long been a fan of using Markdown for documentation in projects hosted on Github. In October of 2014 I decided to migrate from a Wordpress blog to Github Pages, which is powered by limited Jekyll functionality on the Github server side.
With this migration I converted all my articles from HTML to Github Flavored Markdown (GFM), which resulted in much better support for formatting my code examples, tables, strikethrough text formatting, and emojii.
I’ve made use of the following cheat sheets for Markdown syntax:
An issue I’ve had is trying to limit the line length of my markdown. Line breaks do not break apart paragraphs when rendered, however you cannot add line breaks into the URL of the link without breaking the link.
Alternative Syntax
Typically link syntax is provided like so:
[Google](http://www.google.com/)
However if the link and link text exceeds 80 characters, then you end up with hard to read Markdown.
The solution is to use a syntax not commonly mentioned in Markdown guides for linking that separates the text content from the URL.
The links may still wrap at the bottom of the document, but at least the content is easy to read in plain text, even on the command line.
My Links:
* [Github Flavored Markdown][1]
* [Basic Writing and Formatting Syntax - Using Emoji][2]
[1]: https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown
[2]: https://help.github.com/articles/basic-writing-and-formatting-syntax/#using-emoji
One problem I’ve run into is that the numbered references end up provided throughout the page out of order, which bothers me in some obsessive-compulsive sort of way.
Instead you can use the link text itself.
Check out [Spotify] for cool music
[Spotify]: https://www.spotify.com/
Alternatively, you can also use a case insensitive text key if the link text is too informal for you.
[Click here for Google][Google Link]
[google link]: http://www.google.com/
Images
A similar alternative for images can also be used:
![Beautiful flower photo][flower photo]
[flower photo]: /images/flower.png