A couple of improvements to the site generation have been added.

Syntax highlighting

We were previously using literal <pre> blocks in markdown pages so that we could set the CSS necessary for the syntax highlighter. The big downside of this was the need to HTML-escape the code within those <pre> blocks. Using an awestruct 'transformer' it's now possible to use the more natural markdown way of including example code (i.e. using indentation), which means you don't have to worry about using HTML entities for <, & etc.

By default <pre> blocks will not be subject to highlighting. To enable highlighting simply preceed the block with an HTML comment hinting at the language being included. For example

    class Foo() {
        void bar() {

        }
    }

It's also easy to have a page with syntax highlighting of multiple languages, by using an appropriate hint.

For those who are interested, the way this works is having a transformer perform a global gsub on the generated output using a suitable regular expression to pick out the code blocks generated by markdown.

Deep linking

Markdown by itself doesn't allow the author to put id attributes or anchors (<a name="...">) in the generated HTML, which is annoying if you want to link to a particular part of the page. You can of course put <a name="..."> elements in yourself, but:

• It clutters up the nice markdown with HTML.
• It forces you to ensure the uniqueness of the ids you use.
• It's tedious.

Using another transformer we now generate id attributes automatically for all <h*> and <p> elements. For headings we use the heading text (suitably munged into an XML NAME). For paragraphs we use the first few words (again suitable normalized, and also worrying about uniqueness). If an element already has an id then it's untouched. If there's a matching id (or name, since they share the same namespace), steps are taken to disambiguate the generated one.

The long and the short of this is that we can now easily and accurately link into the middle of documents. The caveat is that you should be aware that changing the first few words of a paragraph (or the text of a heading) is likely to break any links which point to it. To prevent such broken links you can always use an explicit <a name=""> at the relevant point.