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.
