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.
It’s been a long time coming, but I have finally decided that the master source code of the Stringtree and Mojasef Java libraries will now be hosted at GitHub rather than Sourceforge. I have been using git to manage the rest of my software for a long time now, but my two main projects have kept their place in subversion at Sourceforge. From now on, if you want the latest source code for either of these projects, please get it from github.
This move has several major advantages. The first is that you can now use GitHub’s “social coding” features to fork and modify the Stringtree and Mojasef code (and I’m always happy to discuss changes and improvements). The second advantage, and the one which tipped me over, is the ability to use git’s clever “submodule” support to include up-to-date Stringtree and Mojasef source code in other projects.
In the short term I will also be keeping the svn repositories up to date with significant changes. For now they are also the best place to find example code which uses Stringtree and/or Mojasef, but I plan to move all the examples over to GitHub in time.
Please let me know if you have any issues or questions about this move.