Div block syntax

[chrisalley]

Given that CommonMark can be converted to formats other than HTML (PDF, etc), creating a syntax for <div> may be too specific. A div is a container element, so perhaps a syntax for “containers” is what is required here.

My points could be applied to containers in general (div, aside, or other); I’m essentially asking whether we need a special syntax just for containers or if existing syntax can be reused for specific use cases. We already have syntax for block quotes, code blocks, and potentially (via an extension) pre-formatted blocks - are there use cases that warrant another syntax that could not be solved by existing block syntax with classes?

[jgm]

What’s under discussion is a syntax for a generic block container. Whether it always renders as a div in HTML, or could render as (say) an aside if certain attributes were set, is a separate issue. (And I’m inclined to think we should be as flexible as possible about how exactly the elements in the AST should be rendered.) And of course it would not be rendered as a div in, say, LaTeX. The term “div” here is being used just to mean “generic block container,” I think.

You’re right that block quotes already exist, and I’ve suggested in a few places that this could be our generic block container if there were a way to add attributes. (The container could default to a block quote if no attributes are specified, otherwise it would render as a div.) However, this suggestion hasn’t been popular for various reasons. People say that the association of this syntax with block quotes is too strong, and also that one might want to allow attributes to be attached to block quotes. There are also some who feel strongly that there should be a fenced generic block container (not just side-marked).

[chrisalley]

A container doesn’t have a purpose until it’s decided what types of items should be placed inside the container.

By discussing generic container syntax in the abstract, there’s a risk that we’ll end up inventing something without an actual use case (that cannot be solved with other blocks).

I think warnings and spoilers can be considered special types of block quote. That is to say, I don’t think using the block quote syntax for these would be bending the association of the > syntax with block quotes too far.

Attributes could be added via consistent attribute syntax.

The main argument I’ve seen appears to be that we need a fenced block syntax. There’s an argument there, but I think it’s seperate from the argument that we need a generic container syntax. We can have one without the other.

[uvtc]

@jgm wrote:

What’s under discussion is a syntax for a generic block container.

Ah. A generic block container. I wasn’t thinking in terms of that. If you want it generic, you could use ; --- type-of-block {.styling #goes in="here"} (with curlies always required — just like with spans). Some examples:

Most-general syntax, here specifying a div (here with class="foo"):

; --- div {.foo}
; Lorem ipsum datsun pompom carfax ronco
; enzo corvette blowfish sockdrawer fob
; condor shoehorn pickle doorstop manwich.

without any styling:

; --- div
; Lorem ipsum datsun pompom carfax ronco
; enzo corvette blowfish sockdrawer fob
; condor shoehorn pickle doorstop manwich.

though, you wouldn’t write that that way, since you could instead just do:

; Lorem ipsum datsun pompom carfax ronco
; enzo corvette blowfish sockdrawer fob
; condor shoehorn pickle doorstop manwich.

Leaving out the block-type (and only supplying the styling) defaults to giving you a div:

; --- {.foo}
; Lorem ipsum datsun pompom carfax ronco
; enzo corvette blowfish sockdrawer fob
; condor shoehorn pickle doorstop manwich.

An html5 <aside> block, with class=“foo” and an extra helping of those handsome dashes:

; ------------ aside {.foo} --------------
; Lorem ipsum datsun pompom carfax ronco
; enzo corvette blowfish sockdrawer fob
; condor shoehorn pickle doorstop manwich.

and here with no styling:

; --------------- aside ------------------
; Lorem ipsum datsun pompom carfax ronco
; enzo corvette blowfish sockdrawer fob
; condor shoehorn pickle doorstop manwich.

Blockquotes:

; --- blockquote {.foo} ---
; Lorem ipsum datsun pompom carfax ronco
; enzo corvette blowfish sockdrawer fob
; condor shoehorn pickle doorstop manwich.

That works, but you’d likely much rather just write that instead using “markdown-native” syntax (“>”):

> --- {.foo} ---
> Lorem ipsum datsun pompom carfax ronco
> enzo corvette blowfish sockdrawer fob
> condor shoehorn pickle doorstop manwich.

> Of course, blockquote
> with no styling.

Lineblocks — there’s no general block syntax because there’s no actual <lineblock> tag, but we’ve still got the specific “|” syntax:

| --- {.foo} ---
| Lorem ipsum datsun carfax
| ronco enzo corvette lomax

| And, of course, line
| block with no styling.

With this general syntax, you’d be giving up the shorthand syntax (where you could drop the curlies and the dot and write ; --- warning instead of ; --- {.warning}), but I think that’s probably reasonable, since it’s not that much of an extra readability cost to pay (and noting that divs simply aren’t going to be as seamless as blockquotes, code blocks, and line blocks, which have their own markdown native syntax and which are used all the time).

[jgm]

@uvtc I didn’t have in mind adding an additional parameter for “block type.” Rather, the renderer could look at the div’s attributes (e.g. class) in deciding how to render it.

@chrisalley I’d personally be happy overloading block quotes. I’ve suggested this many times in various places, but there have always been strong opinions against it.

Advantages:

• degrades nicely with existing Markdown renderers, which already do something sensible with blockquote syntax
• works well with existing Markdown syntax highlighting
• handles nesting well (because side-marked)
• requires little change to parsers

Disadvantages:

• some people think that > must render as a blockquote, even if it is specially marked with attributes
• if we use blockquote syntax for block containers more generally, then we might lose a distinction between a block quote with attributes (say, author=“Einstein”) and a general container with those attributes.
• no fenced form

[chrisalley]

@jgm

some people think that > must render as a blockquote, even if it is specially marked with attributes
if we use blockquote syntax for block containers more generally, then we might lose a distinction between a block quote with attributes (say, author=“Einstein”) and a general container with those attributes.

This is similar to the opinion that image syntax must render an image (rather than other media). I think the arguments discussed in the embedded audio and video topic can be applied here.

[uvtc]

@jgm wrote:

@chrisalley I’d personally be happy overloading block quotes.

Wait a sec. If you’d be ok with overloading blockquotes, why not instead overload the best side-marker of all, the pipe:

| --- {.foo #bar baz="moo"}
| One general block syntax
| to rule them all.

| ------------ foo -----------
| Shorthand for the simple
| case of `| --- {.foo}`.
| Extra dashes on either side
| are allowed.

| --------------------------
| Block with no particular
| styling (for html output,
| this would get you a plain
| div).

And of course,

| Unadorned, this still
| gets you a regular line
| block.

[zzzzBov]

@uvtc

why not instead overload the best side-marker of all, the pipe

Great minds think alike…

Pipe character (|) for <aside>

I was writing a blog post in markdown and I wanted to use an <aside> element for a note within the post. <blockquote> is often (mis)used for such things, which makes sense because writing: > **Note:** lorem ipsum is quite straightforward and commonly renders into some nicely boxed content. However, since the content is not a quote and the HTML5 spec says: Content inside a blockquote other than citations and in-line changes must be quoted from another source this becomes problematic. I thi…

…although fools seldom differ.

[Trillinon]

I think you dismiss the colon too quickly. It may not be a perfect horizontal delimiter, but it effectively functions both horizontally and vertically.

Fenced:

:::::::::::::::::::::::::: WARNING ::::::::::::::::::::::::::
            # rm -rf / – Deletes Everything! #

  The command rm -rf / deletes everything it possible can,
 including files on your hard drive and files on connected 
                 removable media devices. 
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

Side:

: {.warning}
:            # rm -rf / – Deletes Everything! #
:
:  The command rm -rf / deletes everything it possible can,
: including files on your hard drive and files on connected 
:                 removable media devices. 

Combined:

::::::::::::::::::::::::::: WARNING :::::::::::::::::::::::::::
::            # rm -rf / – Deletes Everything! #             ::
::                                                           ::
::  The command rm -rf / deletes everything it possible can, ::
:: including files on your hard drive and files on connected ::
::                 removable media devices.                  ::
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

All three are clean and clear, while using a single character.

[Jerry]

I have tried to explain this to non-programmers and the period, colon, or semicolon for a block syntax seemed easiest for them to understand. Not the pipe, as a table within a block would become unclear (in fenced syntax it looks like the start of a table, in side syntax it has unreadable double pipes).

[uvtc]

What do you think of:

• staying with the symmetry of having both a side-marking
  as well as a fenced/delimited syntax,
• keeping the requirement for the header dashes (to clearly
  signal that this is a block), and
• allowing both the pipe and the colon?

That is, for side-marking, you could use:

| ------------- warning ---------------
| **`# rm -fr /`  deletes everything!**
|
| The command `rm -rf /` deletes
| everything it possibly can, including
| files on your hard drive and files on
| connected removable media devices.


: ------------- warning ---------------
: **`# rm -fr /` deletes everything!**
:
: The command `rm -rf /` deletes
: everything it possibly can, including
: files on your hard drive and files on
: connected removable media devices.

and for delimited syntax you could use:

|-------------- warning --------------
**`# rm -fr /`  deletes everything!**

The command `rm -rf /` deletes
everything it possibly can, including
files on your hard drive and files on
connected removable media devices.
|-------------------------------------


:-------------- warning --------------
**`# rm -fr /`  deletes everything!**

The command `rm -rf /` deletes
everything it possibly can, including
files on your hard drive and files on
connected removable media devices.
:-------------------------------------

[illionas]

The greatest advantage of the colon is only one symbol for the whole thing. I prefer this one.

I don’t see any esthetical problems with the colon used horizontally. It is almost perfectly symetric in either directions and has a nice similarity to the equal sign in creating seamingly a doubled line. I guess that’s why @Trillinon used double colons to fence the box in the third example.

The colon could probably even be used to create a kind of shaded area (at least in monospaced font), because its dots are evenly spaced out. The vertical distance : is similar to the horizontal distance .. – so :: looks like the corners of a square. Thereby a line of colons looks like a shaded line, as does a vertical edge of double colons.

In the following example (of how i think a big button could look like in ascii style:) you can see how the shade effect looks like for areas:

::::::::::::::::::::::
::::::::::::::::::::::
::::::::: OK :::::::::
::::::::::::::::::::::
::::::::::::::::::::::

I think we could even allow any number of colons at the left and right edge of the box. It’s easy to trim them. So if someone wanted to have some shade in the box she could fill it with colons.

A similar effect could be created by using a spaced-out period symbol, but of course nobody would tediously type alternating period and spacebars.

. . . . . . . .
. . . . . . . .
. .  Cancel . .
. . . . . . . .
. . . . . . . .

@uvtc

| ------------- warning ---------------
| # rm -fr / deletes everything!
|
| The command rm -rf / deletes
…

To me the pipe is a little misleading (especially in combination with the dash) in making me instantly think about a table.

Would the initial line of dashed be needed every time or is it optional?

• If it’s optional, then it doesn’t really hint towards how the syntax works for delimited cases.
• If its obligatory, then it makes creating these boxes rather tedious again.

[uvtc]

To me the pipe is a little misleading (especially in combination with the dash) in making me instantly think about a table.

If you don’t like the pipe, you can use the colon. Nice things about having two different characters to use is:

• you can choose which one looks better in which case (maybe one for side-marked and the other for delimited, or colons for when you’re putting a table in)
• when nesting side-marked divs, alternating the side-marker is more readable

Would the initial line of dashed be needed every time or is it optional?

• If it’s optional, then it doesn’t really hint towards how the syntax works for delimited cases.
• If its obligatory, then it makes creating these boxes rather tedious again.

At least three dashes would be required. Not too tedious, IMO:

| --- {.warning #foo}
| This is the minimal and
| most general syntax for
| the div with class="warning"
| and id="foo".

| --- warning
| This is the minimal syntax
| for the div with just class="warning".

|--- warning
| The space after the pipe (or
| colon) is optional.

: --- warning ---
: You can choose to add
: trailing dashes if you like.

: -------- warning --------
: Use more dashes if you
: think it adds readability.

Having the three dashes then the metadata is reminiscent of how it’s done with code blocks (ex. “~~~{.haskell}” or just “~~~haskell”).

In the end, I think the syntax used has got to be readable, fairly minimal, and needs to look classic enough to not go out of style — and I think that suggests flatter characters for horizontal markings, and taller & thinner for vertical. IMO, the multiple colons is too much; it seems too styled, and also I think somehow looks dated.

A last factor to consider: Although the delimited syntax isn’t perfect

:-------- warning
This is an extremely
long warning consisting
of multiple lines and
maybe paragraphs even!

Content copy/pasted in.

It's delimited, for the
writer's convenience.
:--------

the side-marked style is arguably the more markdownish, readable, and would likely be used more often when the reader is expected to read the content in markdown.

[mofosyne]

Can’t see how you can’t have sidemarked colon via overloading definitions. The parser isn’t that much complicated. You are compairing between : and :: ( blankline+::: would indicate div fence start)

e.g.

Surrounding text

:: An Example
:: Of a very minimal 
:: sidemarked div block

More surrounding text.

Term 1
:   Obviously a Definition 1

Term 2
:   Obviously a Definition 2

Also markdownish to me, means looks like something you would do in a text email. While : -- is more easier to parse in some sense, it is not as visually appealing as say.

::::::::::::::::::::::::::: WARNING :::::::::::::::::::::::::::
::            # rm -rf / – Deletes Everything! #             ::
::                                                           ::
::  The command rm -rf / deletes everything it possible can, ::
:: including files on your hard drive and files on connected ::
::                 removable media devices.                  ::
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

Plus markdownish, probbly also means “trivial to explain”. Its easer to tell people to just use lots of ::: rather than | --- . Much like its easier to just tell people to use backtick fences or indentation rather than matching brackets { code here }

[illionas]

@mofosyne

Can’t see how you can’t have sidemarked colon via overloading definitions. The parser isn’t that much complicated. You are compairing between : and :: ( blankline+::: would indicate div fence start)

One can either go down this path, or follow my suggestion from the description list thread and use ~ name : value or ~ name \n: value instead. Definition/description lists that start with a “value” without a name don’t make a lot of sense, so if you don’t allow those, then it would free the single colon as a marker for div blocks (and remove the need for look-ahead in definition lists).

But i actually like the double colon too. As i said: it has that symetry in it. Probably : vs :: is clear enough for the user, but I’m not sure.

[chrisalley]

I think using a double colon would be preferable to the single colon as it would ensure that the block marker is the same when it is used both vertically and horizontally (each double colon is a square in the barrier around the block). Allowing the block to be defined with both horizontal and vertical characters gives the writer a choice. Vertical colons are more Markdownish, similar in structure to blockquote syntax, whereas horizontal colons are more convenient to write. For vertical colons you could have a similar rule to blockquotes, only requiring a double colon at the start of every paragraph.

[illionas]

Obviously the Spec would need to force a space after the :: symbol for nesting (in contrast to >> generating a nested blockquote.

:: outer div block
:: :: nested div block
:: with laziness
:: 
:: outer div block
with laziness

How would you define the upper bar?

I see a difficulty coming up if we want to have the combined variant. You would need to use at least three or more colons i guess: :::

::: WARNING
no left border
:::

[uvtc]

Regarding “colon blocks”, as in:

:::::::::::::: warning :::::::::::::
:: The soup must only be stirred  ::
:: clockwise. Counterclockwise    ::
:: stirrage will result in bland, ::
:: unexciting soup.               ::
::::::::::::::::::::::::::::::::::::

★ They are unreasonably onerous to fully type out. I suspect few would type those closing double colons (and take the trouble to add the right number of spaces so they line up). You’d end up instead seeing all of

:::::::::::::: warning :::::::::::::
:: The soup must only be stirred
:: clockwise. Counterclockwise
:: stirrage will result in bland,
:: unexciting soup.
::::::::::::::::::::::::::::::::::::

:::::::::::::: warning :::::::::::::
:: The soup must only be stirred
:: clockwise. Counterclockwise
:: stirrage will result in bland,
:: unexciting soup.

:::::::::::::: warning :::::::::::::
The soup must only be stirred
clockwise. Counterclockwise
stirrage will result in bland,
unexciting soup.
::::::::::::::::::::::::::::::::::::

in the wild, with users guessing as to which is correct.

★ Side-marking with double colons (or any double any characters) don’t nest very well — that is, it’s a lot to type. This may be especially relevant for divs, where they’re often nested quite a bit.

★ If using colons with delimited syntax — along with nesting — you’re going to end up with multiple closing block delimiters that look like a wall of dots:

::::::::::::::::::::::::::::::::::::::::::
::::::::::::::::::::::::::::::::::::::::::
::::::::::::::::::::::::::::::::::::::::::
::::::::::::::::::::::::::::::::::::::::::

★ It breaks markdown tradition, in that

(A) it’s ok in md to use different characters for side-marking and delimiting (code blocks: spaces for side-marking, tildes or backticks for delimiting), and

(B) md historically uses only a single character for side-marking (ex. blockquotes).

[illionas]

@uvtc

I suspect few would type those closing double colons

Just like with trailing hashes ## for headers. It’s optional and may beautify it. But those who think that the document might be read in plaintext might want the box to stand out as a box.

@uvtc

users guessing as to which is correct.

all three are.

I think the partial examples also have a nice aspect. The “left and top only” looks like a floating box with some shaddow to me.

@uvtc

★ Side-marking with double colons (or any double any characters) don’t nest very well — that is, it’s a lot to type. This may be especially relevant for divs, where they’re often nested quite a bit.

The complexity of nesting also depends on whether we allow “lazyness”. Imo lazy blockquotes look very strange when nested, but well, that’s the trade-off for easy authoring.

Single colons would indeed make typing a little easier if we treat the colon exactly like the > in blockquotes.

That would indeed be a compelling argument for your :--- suggestion, especially if we were to introduce similar fenced syntax for blockquotes (and maybe also codeblocks) list this:

:--- BOX
fenced
:---

>--- QUOTE
fenced
>---

`--- CODE
fenced
`---

|--- CSV-TABLE ?!
fenced csv data
|--- 

@uvtc

★ If using colons with delimited syntax — along with nesting — you’re going to end up with multiple closing block delimiters that look like a wall of dots:

I don’t see how this is more beautiful:

:-------------------------- 
:--------------------------
:--------------------------
:--------------------------

But you could use the minimum number of colons needed (e.g. three maybe), or (optionally) use different lengthes to match different nesting levels visually:

:::::::::::: outer box
::::::::: nested 1
:::::: nested 2
::: nested 3
content
:::
::::::
:::::::::
::::::::::::

@uvtc

★ It breaks markdown tradition, in that

(A) it’s ok in md to use different characters for side-marking and delimiting (code blocks: spaces for side-marking, tildes or backticks for delimiting), and

(B) md historically uses only a single character for side-marking (ex. blockquotes).

(A), yes but this is not out of tradition, but out of necessity.

• The tabbed codeblocks only exist because it’s easier to type (as most editors allow easy indenting. Original Markdown has no fenced blocks at all.
• The blockquotes are copy-pasteable from e-mails etc. Nobody thought about fenced blockquotes then, because again, there were no fenced blocks back then.
• tildes for code-blocks suck anyway. And i think we should go down the logical path of using tripple backticks (or the suggested general block format with ```—``)

(B) true. But why care. Hitting a character twice is not that hard compared to hitting the space bar hundreds of times for indent if the tab key doesn’t work properly in your editor. Also, i think the tradition of markdown is visual sexyness and overview in plaintext more than easy to type (as compared to other lightweight markups).

[Jerry]

Having read the entire topic again, my opinions start to shift towards the original post more and more. I just don’t see the need for the three dashes. Thinking of the writers I have to instruct on how to type their reviews, I think I will tell them this way because so far as I can see now it has the balance between being easy to read and easy to type.

The gig was great!

! {.setlist}
1. Track One
2. A Different Tune

The after-party was OK.

The proposed variations in character (both exclamation mark and semicolon) and fencing (delimited and side-marked) are fine. The proposed syntax for nesting is also great. Not sure whether the end delimiter can be a blank line - I would like to have that explicitly mentioned in the definition when this goes live.

I am assuming the {.className} notation for classes and attributes that has become to most-used syntax will make it into the CommonMark definition one day.

The least controversial way forward, I agree. Just not on the three dashes. Well, I do see how it makes it better readable, I won’t vote against the three dashes.