Rendering a GitHub file in this blog

G'day:
A few days back I released that CFScript documentation effort, which at the time was just done inline as a blog article. I had not decided how best to home it so it could be found. I thought about putting it on GitHub, but in my experience Google is lousy at finding stuff on GitHub. As unimportant as the adamcameron.me domain is in the bigger scheme of things, I seem to rank quite well when it comes to CFML topics (ed: that CFScript page bloody doesn't, mate), so I figured putting it here would be a good first step.

People very quickly started pointing out omissions and cock-ups, which I was duly fixing. But I quickly had enough of that, so decided - to hell with it - I'm putting it on GitHub and people can maintain it themselves.

But I still wanted to display it all on the blog article too. And I wanted it to stay in sync. I knew one could create Gists and embed them in other HTML docs via JS, but I had never found an equivalent for GitHub itself. Also... the page on GitHub is written in markdown, so I'd need to convert it back to HTML before rendering it.

After about an hour of googling and experimentation, I had a solution up and running.

First, I had raw HTML in the blog article, and I needed to convert it to markdown. I couldn't be arsed doing this by hand, so I found an online HTML to markdown converter by Dom Christie at to-markdown.

This did a fair to middling job of converting the HTML as is, and after a few tweaks of the shonky HTML Blogger generates, Dom's converter was generating good enough markdown to use. I polished it slightly, and saved the results to cfscript.md.

Now I needed to get that file loaded from GitHub. I found James Ward's github-files project, which was bloody easy to use. There was no faffing about, just following his instructions worked first time.

So I had the raw markdown string downloaded, but I needed to convert it back to HTML. More googling turned up marked.js on GitHub. It's easy to use, but it didn't do a great job. It messed up code blocks completely, which kinda invalidated it for my purposes.

More googling found me showdown.js, and this worked perfectly.

I had it all working locally, so I uploaded it all to my hosting site, and updated the blog article with the relevant JS calls and... it worked A-OK first time.

Here's the code:

// fetchFile.js

$(document).ready(function(){
    $.getGithubFile("daccfml", "cfscript", "1c6e74c928527ae63ae02e7b203d2b23c16f4291",
        function(contents) {
            var converter = new Showdown.converter();

            $("#codeContainer").html(converter.makeHtml(contents));
        }
    )    
});

And the mark-up in the blog article is simply this:

<div id="codeContainer">
</div>
<script src="http://adamcameroncoldfusion.cfmldeveloper.com/lib/js/jquery-2.1.1.min.js"></script>
 <script src="http://adamcameroncoldfusion.cfmldeveloper.com/lib/js/github-files.js"></script>
 <script src="http://adamcameroncoldfusion.cfmldeveloper.com/lib/js/showdown.js"></script>
 <script src="http://adamcameroncoldfusion.cfmldeveloper.com/lib/js/fetchFile.js"></script>

Easy!

Anyway, just in case you wanted to know how I shared the CFScript docs from GitHub within the blog article... that's how.

Righto.

--
Adam