This page demonstrates a method of getting documentation from readme.md (or other docs) from github and displaying it in github pages in order to maintain documentation in only one place. This method uses Javascript and the Github API to fetch the content in the browser when the page loads.
This is the markdown for the JQuery example. For the no-JQuery example markdown, see joJQuery.md
This is alternative method to those provided by coryg89's Docsync project and bebraw's readme2gh project.
Both approaches are fine but coryg89's is dependent upon a bash script that is installed as a git hook. A problem with this is that if you make a quick change on github, rather than using a git client, your change won't be reflected on github pages. Bebraw's approach is dependent upon a Ruby script.
I wanted to take an approach that always worked, no matter how you change/update the documentation and one that didn't require any sort of out-of-band scripting or check-in policies, etc.
I'll describe how to do this with the readme.md file on Github but it should be easily adaptable to any other documenation you have in your repo.
- Use the Github API and JSONP to fetch the readme.md from Github.
- Decode the base64 content in the response from Github API.
- Parse/Render the markdown to HTML
- Display the rendered HTML
- add
base64.jsto your/javascriptsdirectory in yourgh-pagesbranch- You can get it from Web Toolkit or from the javascripts directory of the
gh-pagesbranch of GithubDocSync
- You can get it from Web Toolkit or from the javascripts directory of the
- add
marked.jsto your/javascriptsdirectory in yourgh-pagesbranch- You can get it from the
/libdirectory of chjj's marked project or from the javascripts
- You can get it from the
- open
index.htmlin an editor and add the following<script>references to the<head>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script>
<script src="javascripts/base64.js"></script>
<script src="javascripts/marked.js"></script>- also in
index.htmladd the following javascript to the<head>(replace githubApiUrl with the appropriate value for the file you want on Github)
<script type="text/javascript">
var githubApiUrl = 'https://api.github.com/repos/bradrhodes/GithubDocSync/contents/README.md';
var contentContainerId = "#readmeContent";
$.ajax({
url: githubApiUrl,
dataType: 'jsonp',
success: function(response)
{
var encodedContent = response.data.content;
var markdownText = Base64.decode(encodedContent);
var renderedHtml = marked(markdownText);
$(contentContainerId).html(renderedHtml);
}
});
</script>- add a block-level container with id='#readmeContent'
- ex.
<div id="readmeContent"></div>
- ex.
- save, add, commit and push all the changes to your
gh-pagesbranch