A selection of syntactic Markdown tricks and advices to get the most out of Pandoc's implementation, which currently has to be the most powerful there is.

1 Fenced Code Blocks

I quite like to choose to use backticks (`) instead of twiddles (~) in fenced code blocks, but purely because the Markdown syntax file bundled with Vim only understands these.

In fairness, though, this syntax file is a mite annoying because, under some circumstances which are still unclear to me, it gets confused with 3-backticks/twiddles code blocks. However, 5 backticks suit it better. For all I know, it might also be related to where the syntax highlighter parses the file from, and I have a feeling that running this Vim command might help, to make it parse from the start of the file and get the full context:

:syntax sync fromstart

2 A Word of Warning About Multi-Line Tables

One thing I love Pandoc for is multi-line tables, offering an extremely versatile and comfortable way to build tables. But be careful with them. I would advise to use border lines to define widths. Crucially, make sure your last row isn't separated from the last border line or the whole page will be rendered incorrectly and very slowly if you generate HTML.

3 Named Anchors

Even though there are many things you can do with links using Pandoc Markdown, named anchors doesn't seem to be one of them, as has been discussed in various places on the web. Luckily, Pandoc allows for regular HTML tags too, so just use a <a name="foo"> sort of tag and be done with it.

4 A Four-Space Rule for Lists

When working with lists, it helps me hugely to keep the four-space rule in mind. It is a rule whereby a paragraph in a list item should start with four spaces. Therefore, the bullet should be placed such that the first line is aligned with any subsequent line, one consequence of which is for instance that a #. will start one space earlier than a -.

In fact, it should be called the multiple-of-four-space rule, because the indentation should be 4, 8, 12, [...] respectively for lists, sub-lists, sub-sub-lists, [...] A canonical example would be:

␣␣-␣Foo

␣␣␣␣Another paragraph
␣␣␣␣␣#.␣Corge
␣␣␣␣␣#.␣Grault
␣␣␣␣␣#.␣Xyzzy

␣␣-␣Bar

␣␣␣␣Another paragraph
␣␣␣␣␣␣-␣Plough
␣␣␣␣␣␣-␣Fred
␣␣␣␣␣␣-␣Quux

This renders:

• Foo

  Another paragraph
  1. Corge
  2. Grault
  3. Xyzzy

• Bar

  Another paragraph
  • Plough
  • Fred
  • Quux

5 Avoiding Unaesthetic Vertical Spaces with Paragraphs in Lists

The problem comes when you start having multiple paragraphs in a single item within a list. Consider first a simple, unproblematic case with only single-paragraph items:

 #. Foo
 #. Bar
 #. Baz

... renders:

1. Foo
2. Bar
3. Baz

Note how the items are nicely close to each other. I'm now adding another paragraph to the first item:

 #. Foo

    Another paragraph
 #. Bar
 #. Baz

Rather annoyingly, it has the side effect of adding vertical space between the second and third items too. What actually happens is that adding paragraphs in items means Pandoc wraps them up in <p> tags. For some reason, it will also wrap up the contents of other items in <p> tags, even if they are only made of a single paragraph each:

1. Foo

   Another paragraph
2. Bar

3. Baz

One (rather obscure) way to address this is to wrap up in <div> tags single-paragraph items following a multiple-paragraph one:

 #. Foo

    Another paragraph
<div>
 #. Bar
 #. Baz
</div>

This will indeed work, and note in particular how the sequence in numbered items isn't even disturbed:

1. Foo

   Another paragraph
2. Bar
3. Baz

6 References

• Pandoc User's Guide
• First syncing method
• html - Cross-reference (named anchor) in markdown