Using Markdown in GitHub Pages

I really like the idea of GitHub Pages, and the way that it helps to manage the documentation for a project, bringing it in line with the same practices and tools used to manage the software development process. Of course, I would have been slightly happier if GitHub had chosen to use my own broadly-equivalent site-generation tool “Site Grinder” rather than Jekyll, though 😉

Most of the example sites linked from GitHub use html or textile for page layout, but I quite like Markdown, and wanted to use that instead. According to the Jekyll documentation, markdown is supported, but it took several attempts to get GitHub pages to recognize and transform my Markdown encoded project home page. The trick was to ignore the implication in the Jekyll documentation about file extensions. Example textile files have a “.textile” extension. Example HTML files have a “.html” extension, and so on. However, Markdown files only seem to work if they have a “.md” extension. Other common possibilities such as “.mkd” or “.markdown” are not recognised, and result in the raw file content being passed to the browser.