Rendering Code Snippets on a Static Website

Rendering code in a pleasing format on a webpage - including bells and whistles like line numbers and syntax highlighting - is an easy thing to take for granted after spending a lot of time with Markdown renderers like the one GitHub offers. But bringing the same capability over to a static webpage with no "help" from outside scripts or compilers, is not trivial. Making the following appear took a little bit of work:

#include <iostream>

int main() {
std::cout << "Hello World" << std::endl;
}

What goes into rendering this?

• C++ uses the symbols < and > for including the standard libraries, for comparisons, and for the stream insertion/extraction operators. But HTML also makes heavy use of these, meaning that they will get interpreted as HTML tags and be hidden from the user's view. To prevent this, all of the symbols must be replaced with their HTML-escaped variants: every < must be rewritten as <, and every > must be rewritten as >.
• Although HTML provides the <code> and <pre> tags for designating code blocks and rendering them with the desired whitespace, no syntax highlighting is provided (not that one would expect HTML to do it, but it's now become standard practice for code presented online. To color the text above, Google's code-prettify script was used. But if one wanted the code to render In Full Color without any on-load rerendering, one would have to add <span> tags with the desired colors or syntax, throughout the code sample. (This is what the Google script is actually doing - it just does it after the page is loaded!)

Neither of the above is a huge problem - but it conflicts with two things that some people might be after:

• Minimize load times by "compiling" the <span> tags beforehand
• Store the code in its native format - HTML-reserved symbols and all - so that it can be run and tested before inclusion in the webpage

I'd previously thought there was a lot of craft in writing HTML code from scratch, and that it was the way to go for constructing a static website. "Compiling" HTML was only really worth the extra infrastructure for running a dynamic website. I am now convinced of the opposite: even for small static websites, it probably makes more sense to handle things like code inclusion and highlighting (as well as things like using the same header and footer across different pages) by using a templating engine (or some other tool that assembles the HTML for you.) That is the subject of this page.

Home