kramdown and hljs for the documentation

from: Lin Jen-Shin (godfat)
date: Thu, Feb 16, 2012 at 8:47 PM
subject: the documentation system

So... for the API documentation, our work process would be:

* edit: ./doc/api.md
* run: ./bin/doc to generate the document to doc/index.html
* run: ./bin/gh-pages to deploy the document

We're using kramdown, which is a markdown extension,
which we can specify CSS information for a given node.

We're also using hljs to highlight the code.

So here's what we'll do for a duplicated snippet.
Suppose this is the original snippet:

* /status

      {"status": "ok"}

And we'll do this instead:

* /status

      {"status": "ok"}
  {: .javascript}
{: #status}

Notice that we're telling hljs that particular JSON should be
highlighted with JavaScript syntax. This is a kramdown syntax
to mark the code block's class as "javascript", which hljs would
infer from.

We also mark the whole snippet's id as "status",
this is for future reference. Whenever we want to insert
a particular snippet into a place, we can do this:

<div class="insert">#status</div>

I'd written a simple JavaScript which would walk through
all nodes with class "insert", and replace the inner HTML
from the "#status" to the content of that particular node.

This way, we can easily insert any snippet into any place
in the document, with kramdown's markdown extension
and a very simple and straightforward HTML tag...

So basically the syntax highlighting and duplications insertion
are done on runtime via JavaScript. This way, we don't need
a special documentation system such as YARD or Doxygen...

Hope this would work out.

You can find my JavaScript code in the kramdown template on gist.