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>.
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.
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.
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
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?
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.
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.
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>?
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.
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.
>>> 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.
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.
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 ;.
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:
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.
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.
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.
^^^
! # 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.