I started working on Ocam almost two weeks ago. I’ve had a need recently for a way of writing documentation for a couple of projects I’ve been working on. I didn’t want to have to write a bunch of server code or to have to install a database to back a blog engine. I wanted something simple and elegant.
In evaluating different documentation systems I like, I’ve come across several nice examples, including Backbone and Orchard. I was curious about how they approached their documentation. I little research lead me to the OrchardDoc project on GitHub.
The OrchardDoc project is mainly documentation content, as you might expect. I didn’t find much code there. There were a couple of things worth noting, though. The first is that Markdown is the primary means of authoring content. The second is that it requires ASP.NET to run. I liked the Markdown approach, but I was looking for something that didn’t have server side dependencies.
Based on one of the assemblies in the Bin directory, it appeared to use NuGetDocs. A little searching lead to this post which confirmed it. The NuGetDocs project makes interesting use of the MarkdownSharp component to allow Markdown to be used in an ASP.NET environment.
So here were two two impressive .NET projects and they were both using a Markdown based documentation system. I started to look for alternatives that didn’t have the server side dependency.
Jekyll is probably the best known Markdown site generator. It’s used by GitHub and was written by the Cofounder and CTO of GitHub, Tom Preston-Werner. I installed it and played with it a bit. Although it’s written in Ruby, it uses Pygments, which is written in Python, for syntax highlighting.
After using it for a little while, I started wanting to make modifications. Then I got to thinking about how great it would be to have a system like Jekyll that used the idioms that I was familiar with from ASP.NET MVC. In particular, I really like the Razor view engine and their approach to code and markup. I had known about the RazorEngine project, so I started looking into the possibility of writing a stand-alone console app that would have all the features I wanted in a simple package.
I had been thinking of writing a content platform for some time, but I always abandoned the idea because there isn’t a great syntax highlighting package for the .NET platform. The fact that Jekyll called out to Pygments, which is written in a different language, was a kind of permission for me to go forward.
I uploaded the result about two weeks ago. It’s still a work in progress. Please feel free to contact me with questions or comments.