People have been asking me to write the Software Carpentry instructor's guide in Markdown instead of HTML, mostly so that it will be easier for other people to review and contribute. I was initially against the idea because standard Markdown lacks so many features that I'd basically be writing HTML with back quotes instead of <code> tags, but it turns out that Pandoc's variation on Markdown provides a lot of what I want—a lot, but not all. After converting the section on databases, I've come up against the following:

Pandoc won't number figures and insert those numbers in references. I can do this by inserting \label{...}'s and \ref{...}'s if my target format is LaTeX, but I want HTML.

There's no way to attach a CSS class to a table. I can do this to a heading by writing:

### Heading Title {.some-style}

but the curly-brace syntax doesn't work with tables. I want to do this so that I can display the output of SQL queries as HTML tables, but style them in a particular way.

I can't put styling information inside a pre-formatted code block. I frequently want to show a snippet of code, then show it again with some minor changes highlighted. Using HTML, I do this as:

the original <span class="highlight">and the changes</span>

but if I do that inside an indented (pre-formatted) block, it's rendered literally.

Most of the major sections in each chapter open with instructors' notes. As pure HTML, this looks like: