Wow! This topic has been discussed by many folks across numerous threads for a long time. I don’t believe it’s been resolved, but div syntax is certainly something that’s been wanted for quite some time. For your consideration, some givens, a few observations, then a possible solution.
Givens
Markdown already supports side-marking syntax for blockquotes (>). It works great.
Pandoc supports a delimited / fenced syntax for code blocks (using ~~~, and also backtick).
~~~
10 print "hi"
20 goto 10
~~~
That delimited syntax works really well.
Opening mark is the same as the closing one (unlike, say {{{ ... }}}).
Side-marking syntax is easier to read. Delimited syntax is more of a convenience for writers (doesn’t read as well, but makes it easy to cut/paste into delimited blocks).
Commonmark / Pandoc / Markdown needs a syntax for divs; both a side-marked and a delimited syntax.
Side-marking looks best when the character/glyph is at least sort of vertically-oriented. Delimited syntax looks best with a horizontally-oriented character.
You want to choose a syntax that is markdownish. To me this means:
- It shouldn’t look too much like markup,
- shouldn’t be hard to remember,
- should be mostly obvious to the reader what it means,
- tough one: should just look good, catch on easily, and be resistant to going out of style (tall order!)
- no overly ornate syntax. Ideally, readers should almost not even notice the syntax.
You’d like the syntax characters to look like what they mean (like how > looks like "indent this to the right). But divs don’t have any palpable meaning…
Observations
People like the colons, but they don’t really look great repeated (“:::”). They also conflict with definition lists (if your flavor of markdown supports those). Exclamation marks look like yelling. Not many characters left to choose from!
Some commonly used block-like “syntax” I’ve seen or used:
+++ John wrote:
> What time does
> your flight land?
,---[ cooking tip ]---
| If it's burnt, you
| cooked it too long.
`---
-------- Warning --------
Keep peanut bag closed
to avoid squirrel attack!
-------------------------
Conclusion: headers work. Everyone knows immediately on-sight what they’re supposed to mean. They’re great.
It’s becoming increasingly clear that the way to style things is to put that info in curlies: {.some-class #some-id foo="bar"}. Note, Pandoc has recently added support for styling spans: [foo]{.bar}.
Proposed Solution
Edited using improvements added below-thread.
; --- {.warning}
; Toast is very hot. Butter
; with care, and handle only
; with tongs.
That is, the div character (; or !) followed by three or more dashes, and optionally the metadata for the div in curlies. For simple ones like the above, curlies and dot are optional. Further, trailing dashes allowed.
; ---------- info -----------
; Tea is now available in
; the dining car. Please sip
; quietly.
Nested looks like you'd expect:
; --- {.outer}
; Please make sure your feet
; are clean before entering the
; pool.
;
; ! --- {.inner} ---
; ! Hey, this
; ! means you!
;
; Mats are located by
; the entrance.
Delimited syntax:
; --- {.info}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea.
; ---
Though, I think it looks better with more hyphens:
; --------------------------------------------- {.info}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea.
; ---------------------------------------------
Nested works as you'd expect:
; --- {.outer}
Outer block!
; --- {.inner}
Hi from the inner block!
; ---
Back to outer.
; ---
Some nice benefits of this solution:
- side-marked and delimited syntaxes mesh nicely together
- meshes well with current md syntax (fenced code blocks, side-marked blockquotes)
- doesn’t look too much like markup (or less like markup than, say, something like
{{ ... }}) - div character “
;” doesn’t have any strong connotations (like how>is “shift right”, or even how:could be associated with definitions).!has connotations for warning/caution/attention, which is often wanted. - the div headings (“
--- {.some-class}”) actually add readability; without the “---” it might look like gibberish content on the first line - the delimited syntax only adds one leading character, and then lets you use dashes, which look great.
Seems to me like it may be the least controversial way forward. Thanks.