Div block syntax


#6

I can’t help but wonder if…

<aside class="warning">
Keep your hands on the keyboard at all times.
</aside>

…would be clearer than some of the proposals that have been suggested. This syntax is just HTML and is already supported and works well with nested containers.

Warning boxes are also a kind of block, so it may be fine to override the existing block syntax and simply add a class, rather than inventing a new syntax. E.g.

> .warning 
> Keep your hands on the keyboard at all times.

> .spoiler 
> This is a spoiler.

A post-processing step could then add an additional markup required for rendering a warning box or a spoiler, but would fall back to a blockquote if that step isn’t available.


#7

except once you use <aside> you can’t use markdown within it. I recall reading a proposal to add attributes that enable markdown within HTML elements. I’m not against flagging elements as being markdown-enabled.


#8

@chrisalley, I think you may be conflating two separate problems:

  1. finding a syntax for <div>
  2. finding syntaxes for additional tags, for example, <aside>. (Like how we currently have “>” for <blockquote>s.)

My purpose here is the first.


#9

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?


#10

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).


#11

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.


#12

@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).


#13

@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

#14

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.


#15

@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.

#16

Great minds think alike…

…although fools seldom differ.


#17

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.


#18

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).


#19

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.
:-------------------------------------

#20

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 . .
. . . . . . . .
. . . . . . . .

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.

#21

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.


#22

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 }


#23

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.


#24

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.


#25

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
:::