puppetlabs/showoff — pull request #68 by binford2k (2013-07-19 22:19:30+00:00)
Title: alternative to double markdown parsing

Fixes #24

This adds section tags that will work much better than the `.handouts`
and `.notes` tags that we used before. You simply open a section with
`~~~SECTION:~~~` and close it with `~~~ENDSECTION~~~`.

For example, what was:

.handouts These are handout notes.
.handouts I have to prepend each line with that string, which means that
.handouts
.handouts * bullet points
.handouts * headlines
.handouts * and other block level elements
.handouts
.handouts need a second pass through the markdown renderer.

Can now be written as

~~~SECTION:handouts~~~
These are handout notes.
I can just write any markdown I like, which means that

* bullet points
* headlines
* and other block level elements

render with a single pass through the markdown engine.
~~~ENDSECTION~~~

No more need to prepend `.handouts` to each line, and that's where the
benefit comes. Because we're not munging lines, we don't need to parse
markdown twice, so we don't have the crappy double/triple escape bugs.
It also means that we can finally include code in handout notes without
wacky unicode bullshit.

This is going to take a bit of a transitional period, so I'm leaving
both markup algorithms in place for approximately one month while we
start transitioning the material to the new method. When we release the
next revision, I'll push out another showoff update which removes the old
method, which should also speed things up quite a bit.