Using Github Pages for your help docs

Posted: 2014-02-13 08:02:00

Really impressed with how this came out.

Using Github pages with no theme we can use that repo to then pull in our help files to our local project via a JSON request. This separates documentation from the project so anyone on the team can checkout the git branch for the docs, make an edit and push to that branch which then shows on the site in minutes.

To start with take the repo you are using to make a new branch called gh-pages as noted here Github Docs 

Once you have that branch start writing your Markdown files. 

I have one index.md that always links to the files in the folder.

So when I am done the root looks like this

/index.md

/images

/foo.md

/bar.md

And if you where to open the index.md you would see this (view the raw version)

So I am setting up this file to link to the files I am making. This will allow our help page to have an index.

Then for foo.md I could do something like this (view the raw version)

I will show in a moment the javascript to make the youtube link open in a new page.

When I am done with my markdown I run this at the command line

for i in ./*.md; do markdown --html4tags $i > ${i%.*}.html; done;

and I end up with with my html files all made for me. [1]

Then I git add, git commit and git push this back to origin gh-pages.

That is it for docs.

In the app that uses these docs I just have a link that triggers a library to open and show the content.

I used this library for the slide out http://srobbin.com/jquery-plugins/pageslide/ 

I am not totally sold on the library.

Finally the JS code to pull in the Github docs. 

 

Finally I have a route that gets it for me and cleans it up. This could have been done in JS but I did it this way

Note

[1] I will be using the markdown to html library soon so we can just leave the md as is.


Tags:

github