Pipe character (|) for <aside>


#1

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 think as a simple extension, it would make sense to use a | character to indicate an <aside> with all the same syntax and rules as would be used for > to indicate a <blockquote>.

The example from above would become:

| **Note:** lorem ipsum

And would render to

<aside>
  <p><strong>Note:</strong> lorem ipsum</p>
</aside>

Div block syntax
Fenced block but not fenced code block
#2

In Pandoc, line blocks are used for preformatted text (<pre>).

Discussion relating to line blocks in CommonMark.

In Markua, A> is used to represent an aside, with other letters combined with > representing different types of asides (e.g B> for blurb, W> for warning). Perhaps something similar could be considered for CommonMark. Although using a more generic approach might be preferable, such as block directives.


#3

I should add that I’d also considered suggesting a blockquote starting with >| in much the same way that >! is often used for spoiler text, but I wanted to avoid a syntax that would likely conflict with the proposals I’ve seen for table extensions.


#4

I doubt | will ever be reserved for aside. Too specific. But if you use javascript parser, there is markdown-it-container for markdown-it and you can crease custom extension like

````aside
**Note:** lorem ipsum

That's not ideal, but better than nothing.

#5

I’m not sure I follow why | for <aside> is any more specific than > for <blockquote>. I hardly expect it to be more than a niche extension to expand on the HTML elements that are available for use within markdown without needing to switch to raw markup.

I’ve considered proposing

: term
; definition

to generate

<dl>
<dt>term</dt>
<dd>definition</dd>
</dl>

along with a number of other extensions. Do you feel that these sorts of proposals are not abstract enough?


#6

I don’t remember topic link, but | was discussed in context of something more generic (like lyrics).

Also, aside is not container type, it’s a layout (like highlighted “info” block and so on). It’s not optimal to reserve unique markup for single layout.

That’s only my personal opinion.


#7

According to whom?

per the spec, <blockquote> is in the following categories:

  • Flow content
  • Sectioning root
  • Palpable content

and it may contain Flow content.

per the spec, <aside> is in the following categories:

  • Flow content
  • Sectioning content
  • Palpable content

and it may contain Flow content

Please explain what makes <blockquote> special, given that it too is often displayed as a “highlighted ‘info’ block”. Furthermore I see no reason that we couldn’t have extensions for <article>, <section> as well.


#8

Pipe should be used for tables.

Better decorate a blockquote marker (e.g. a>)


#9

I’ve added this topic to the Wiki’s list of proposed extensions under “Directives”. If you visit the page you’ll see that we’ve had a number of similar discussions about block elements. Perhaps a generic syntax for blocks can be reused for <aside>?


#10

I see no reason that they need conflict. tables need rows, which should make the two usages distinct.


#11

The last thing markdown needs is an alternative abstraction to build any HTML element. Once you start down that road you’re going to end up needing to deal with encoding and escaping and might as well write raw HTML. The reason markdown is so popular is that the common elements in HTML have been simplified in such a way that writing can be done quickly without having to think about such things.

It also makes the source portable and easy to digest without needing to be rendered. Once you start to make a “generic” syntax the utility quickly drops.

For example, Discourse’s own quote syntax of:

[quote="chrisalley, post:9, topic:2227"]
Perhaps a generic syntax for blocks
[/quote]

is not something I would be able to write accurately if there weren’t already quick-insert buttons in the UI. And frankly it’s ugly. I’d have preferred a dedicated syntax along the lines of:

> Perhaps a generic syntax for blocks
> 
> -- @chrisalley, 2227/9

because it’s terser and easy to author without needing to rely on external automation.

So, as far as aside is concerned, I find using a generic syntax such as

:::aside
**Note:** lorem ipsum dolor sit amet.
:::

to be far too verbose and distracting where

| **Note** lorem ipsum dolor sit amet.

is clear, concise, and in-line with the similar blockquote syntax.


#12

I’d find a custom fence acceptable, too:

>>>
aside
>>>

In plain-text email, I’ve regularly used a | line prefix for quotations from outside the thread, but I’ve also seen it as a general quotation line-prefix (just like > and : either repeated or prepended with author intials). It may become tricky with tables, though, because you probably couldn’T use a literal | inside an aside without it being treated as a table instead.


#13

>>> won’t work without compromising triply nested blockquotes:

example

Certainly it’s unlikely people would want to use triply nested blockquotes, but I see no reason to introduce a conflict in that regard.

My understanding of the proposed pipe-based table specs is that they require | prefix and | suffix.

| table example |

whereas the <aside> proposal wouldn’t have | suffixes

| example
| | example

and additionally, literal | characters in an aside would need to be escaped like literal > characters in a blockquote:

> example \>
| example \|

and given the table specs using \ to escape the | would remain consistent.

I admit the duplication of use of the | character could run into trouble with tables, and any extension specifications would have to keep compatibility with other extensions in mind.


#14

Literal > do not need to be escaped in block quotes

However, escaping literal | in an aside block does make sense.

I implemented an aside extension in my parser by copying the block quote parser, changing the marker and adding a condition that the line cannot be terminated by a | to distinguish it from tables. Did not add the escaped trailing pipe test, but other than that it is simple to implement.


#15

I’d recommend against using | in an aside syntax extension, since this already has an established use for line blocks (in pandoc and perhaps others), and might at some point acquire that use in CommonMark. Use a different character, maybe ;.


#16

Actually, they do, just not always, and my previous example is bad.

If you want your text to literally be > o hai within a blockquote, you’re going to need to escape the > to get

> o hai

Otherwise, > > o hai would produce:

o hai

Which is obviously wrong.


#17

I’ve been contemplating a bunch of options for this, some of which seem like they would be more effort than they’re worth, but one that I’ve been tossing around is to use () fencing because parentheticals are essentially inline <aside>s.

Something like:

(((
this content is tangentially related to the main content
)))

It has the advantage of still being easy to type with minimal effort and being readable in text as-is without needing a significant amount of thought. Using different opening and closing characters is a bit odd given the rest of the standard, but it would allow <aside> to be nested if-needed (and that should be rare anyway, so the fact that it’d look a bit ugly isn’t a major problem in my mind:

(((
aside 1 aside 1 aside 1
(((
aside 2 aside 2 aside 2
)))
aside 1 aside 1 aside 1
)))

Overall, I’m not particularly sold on worrying about compatibility with existing solutions for optional extensions. My opinion is that extensions should be able to create an ideal markdown syntax without being held back by the decisions of past developers.


#19

Funny that the term generic is used a lot, as in trying to make things generic. But I find the blockquote and pre tags very specific. My team of reviewers would never use the pre tag, which I think is very developer-y. The blockquote is rarely used.

The aside tag would be used a lot more. It would be used for a short quote for grabbing the causal reader’s attention, the often-mentioned warning or info blocks (although a div tag would still be better for that).

Common, or generic use of custom blocks would be stuff like a setlist in a concert review, an introductory paragraph to a longer article, the question paragraph and the answer paragraph in an interview, the text aid by Death in Terry Pratcett’s book Mort, the text a robot says in an sci-fi novel, etc. All certain types of blocks that can be made custom by an attribute and used in both HTML and PDF or print.

So if we’re talking common, a fenced block with attribute is more common than a code block or blockquote which in my opinion are very specific.

Of all the characters mentioned for a custom block, I think the colon (:) or semi-colon (;) would be easiest for my writers to understand. Or the > for a blockquote with an attribute but then I would prefer it to become a div tag and not a blockquote tag.


#20

If it weren’t for the HTML elements i would suggest the < symbol. However, i do quite like the ^. It’s similar to the > blockquote, still i guess a good leftward delimiter.

^ Dicat impetus deseruisse duo
^ cu, ut volumus delicatissimi
^ mea, eam prompta voluptua
^ intellegam ut. Duo alii
^ eleifend ne. Eu dicat volumus
^ mel, eu eum causae pertinax.
^ Mea iriure gubergren cu, sea
^ eu sint facer iisque.

Imho fenced looks good too:

^^^
Dicat impetus deseruisse duo
cu, ut volumus delicatissimi
mea, eam prompta voluptua
intellegam ut. Duo alii
eleifend ne. Eu dicat volumus
mel, eu eum causae pertinax.
Mea iriure gubergren cu, sea
eu sint facer iisque.
^^^

#21
! # Warning
! We could easily bikeshed this forever.
! However, I'm going to bring up the exclamation point.
! It already means "call attention to this" in English, after all.