Pages

Markdown to HTML for documentation

I've been trying to figure out the best way to make supporting documentation available.  During the development phase of our projects the documentation is in flux a lot,  so it needs to be something easy and flexible.

My latest attempt was to use Github Wikis:

https://github.com/jiscdev/learning-analytics/wiki

That gives us nice clear documentation, and is really easy to manage, track changes etc. The problem is it's not terribly friendly for non-techies.

My solution was to use the a combination of Sails.js (and overkill really!) and Showdown (https://github.com/showdownjs/showdown) to create a simple service that takes a wiki pages, formats it, and changes the URLs so that they also link to the formatted version.  The end result came out pretty well:

https://docs.analytics.alpha.jisc.ac.uk/docs

The only really hacky thing I had to do was parse the incoming text for <pre> tags, and manually add <br/> at the end of each line to get code to format well.  The end result of that worked pretty well too:

https://docs.analytics.alpha.jisc.ac.uk/docs/lrw/Technical-Guide:-Basic-UDD-Queries


No comments:

Post a comment