Flat code block syntax (was seemingly no good way to end bulleted list and start code block)

John MacFarlane jgm at berkeley.edu
Sun Oct 7 12:10:36 EDT 2007

> I'm not sure the indentation feature is so useful. After all, you can use

> the old syntax if you want indentation. What do you think?

I'd prefer to keep it simple and leave out the indentation feature.

> I'm not against option 2, but I don't see it as a replacement to option 1

> (for the reasons enumerated below).


> It also has more potential of breaking existing documents. Imagine if

> someone put multiple paragraphs and headers in a big list item, and one

> header is preceded by two blank lines to make it stand out more. The

> content of that list item would become a code block. Not pretty.

Good point.

> We could allow this only between list items: add an additional blank line

> to break out of the current list; but not working for code blocks. The

> worse that could happen to existing documents then is that some lists could

> be broken into separate consecutive lists; that's much less damaging than

> turning some list item's content into a code block.

This would complicate parsing quite a bit. At this point I'm inclined
to keep changes as simple as possible, and just to implement option (1)
without any version of (2).

On the issue of ~~~ vs ===, you give two reasons for preferring ~~~:

(a) Because ~~~ is not used for Setext headers, we would not need to
require a blank line before a code block. You could have a code block
like this
which would not be possible with ===.

(b) Because === already has a use in markdown, using it to mark off
unindented code blocks might confuse people and parsers who aren't
familiar with the new syntax. Non-extended markdown parsers would
parse these code blocks as a regular paragraph followed by a header.

On (a): Partly because ~ already has a use in pandoc for inline
text formatting (~~strikeout~~ and ~subscript~), and partly because
it makes parsing easier, I'd be in favor of requiring blank lines before
and after the new-style code blocks.

On (b): Non-extended markdown parsers will make a mess of the
new code blocks with either syntax, since they won't know to interpret
the text between ~~~ as verbatim text. I don't see a big advantage
here for the ~~~ syntax. Also, as I noted, in pandoc ~s are already used
to indicate ~~strikeout text~~ and ~subscripts~. I can see that the ===
syntax might cause problems with existing syntax highlighters, though.

Perhaps an alternative would be to use ++++s instead of ~~~~s.
Advantages: Not currently used for anything in markdown or extensions,
vertically centered on the line in most fonts. Disadvantage: ugly?

I'd be interested in hearing what others think. Although I have a
preference for ===, I'd be willing to go with ~~~ just to prevent a
proliferation of different syntax extensions.

One more thought. I think it would be useful to allow something like

inlineNote = try $ do
char '^'
contents <- inlinesInBalanced "[" "]"
return $ Note [Para contents]

If the string of ~~~~s that introduces the code block contains a
parenthesized string, this would be treated as the "class" attribute of
the code block. This would make it possible to postprocess the
output with a syntax highlighter, or use a javascript syntax


More information about the Markdown-Discuss mailing list