The spec calls them “code blocks,” but never says they’re “for code only.”
All it says is that “the content is treated as literal text, not parsed as inlines.” This is incompatible with one of your examples (“wrapper with some attributes for inner markdown”). And I wouldn’t want to change that: it would create too much confusion if sometimes the contents were parsed as markdown, and sometimes not. But it is compatible with many uses other than code.
Remember, the spec doesn’t prescribe how these elements are to be rendered, just how they’re to be parsed. So, rendering a code block with a certain class as, for example, a diagram, is compatible with the spec.
I think that if you want a fenced construct whose contents are parsed as commonmark, a different syntax should be used. Pandoc uses ::: for this.
Hm… thanks, that means, diagrams should be fine, and only info string format should be recommended, to unify different extensions look.
That may look logical, if we work with well structured syntax, but markdown is not strict, and i can’t find any thing to become better:
User will have to remember, fenced container with commonmark should have different guard. Why?
Reading will not be more easy.
Programming will not become more simple (and users should not suffer from programmer’s difficulties).
IMO, the principal feature of fenced block is how to make nesting with length of “```````````````````````````” & info string. Everything else is not “mandatory”.
Let’s consider needs of real world. Quotes in Discourse. Everybody use it. I think, everybody will agree, this example is not artificial.
Number of such cases (blocks with markdown inside) is very small, and will not exceed 10 in total (IMO). I can count ~ 3 now: quotes, notes and asides. The most will use only one - quotes (and case with quotes can not be avoided or replaced with > blockquote)
We can:
Consider those as exclusions for existing fenced blocks markup
Create new guard ::: for such blocks
Create unique guard for every block.
I think (3) can be dropped, as not convenient (difficult to learn/read). We stay with (1) and (2). IMO:
(1) exclusion for existing fenced blocks is normal, because all markdown is a huge combination of exclusions.
(2) will not give any benefits for typing/reading. Users will be pushed to learn different markers without clear reason “why” (from user’s point of view).
Since demand for fenced-style quotes (as extension) is obvious, it would be nice to formalize it somehow. Waiting more years will not change anything - demand for quotes will not disappears. Now site owners have to invent custom marks, and that’s very bad for future.
The most important step is to declare recommended guards (probably, ```quote or :::quote). I would vote for first one (see reasons above).
Looked as “a certain class”, how is “formatted text” different from “diagram”? Both have source code, and both have a graphically rendered presentational form.
If it ok to graphically render the diagram described in this block:
``` mermaid !
diagram code here
```
then per logical consistency it should be ok to graphically render the formatted text doc described in this block:
``` rst !
reStructuredText code here
```
and likewise for this block:
``` markdown !
markdown code here
```
The uses for the latter are common on this forum itself. in many discussions, we want to show source code and then demonstrate how that source code is rendered.
In fact, the CommonMark spec.txt has that need itself, and was forced to use a custom solution.
Consider those as exclusions for existing fenced blocks markup
Create new guard ::: for such blocks
Create unique guard for every block.
There was a very extensive discussion of this on this forum a number of years ago.
If it’s going to affect parsing, and not just rendering, then we need a clear distinction between fences whose contents are taken as literal text and fences whose contents are parsed as commonmark.
I am against making this distinction using English words: e.g., ``` quote starts a fenced section whose contents are interpreted as commonmark and put in a block quote. People write in lots of languages other than English, and it’s awkward and unmarkdownish to use English words to indicate structure.
So, something like ::: is better. My recollection from our earlier discussion, and many other discussions on pandoc forums, is that people preferred fence marking to side marking, and that ::: was the most sensible fence choice. It’s already fairly well established in pandoc and everything that uses it (RMarkdown, etc.).
If you prefer ::: for “quotes”, what to do with “notes”, “asides” and other nestable containers? We can not invent unique guard for every case.
I understand intent, but IMO it’s very strange to care about structure while english tokens still used in other places - code highlight, math (TeX), diargams and so on.
If you prefer ::: for “quotes”, what to do with “notes”, “asides” and other nestable containers? We can not invent unique guard for every case.
To be explicit: I don’t think we need a dedicated fenced syntax
for quotes (or asides or…). What might be useful is a generic
container that can be adopted for lots of purposes on a case by
case basis.
For flexible extension, we need:
a generic container for literal inline text
a generic container for parsed inlines
a generic container for literal blocks
a generic container for parsed blocks
Fenced code blocks can serve purpose 3. But commonmark currently
doesn’t have anything that can serve purposes 1, 2, or 4.
I understand intent, but IMO it’s very strange to care about structure while english tokens still used in other places - code highlight, math (TeX), diargams and so on.
These don’t affect parsing/structure. They’re part of the
content, not the form.
Things you describe are very similar to “maruku syntax”. IMO, it’s usability is ~ like html (between “strange” and “ugly”). Good for fallback, but not for main use.
I think, well known cases (like quotes & spoilers) need more nice syntax, than universal one (maruku-like).
I understand the difference. I don’t understand why english words in structure will be a problem for users.
(The former is a valid pandoc fenced div; you only need the braces if you have more complex attributes.) But the different kind of fence makes it clear that the content is to be parsed as commonmark rather than literal text.
Anyway, what you seem to be proposing is to make commonmark much more like asciidoc, which uses English words to mark out a large number of built-in container types (quotes, asides, etc.) corresponding to the docbook document model.
I meaned, ugly is {#id .class key="val"}. About quote above, IMO both cases are similar and use english keyword. But in case of :::quote, user will have to remember, “quote needs different marker”. That’s possible, but strange.
IMO this looks sometime like desire to force users simplify life of programmer.
I see it a bit different. Number of really required nestable containers is very limited. Since markdown is chaotic set of random rules, couple of additional exclutions will not change anything.
Anyway, it would be not nice wait several years more. To be constructive, i suggest postpone ``` vs ::: battle for several days, and take care about info string format recommendations.`
It’s possible that I’m not quite following here but I am curious - what sorts of situations would you want to use a code fence-like area for text (quotes) that isn’t already served by the quote tool?
There are a couple that come to mind where a fixed width font is useful -
tables (in uses where some variety of table markdown isn’t available)
poetry (where the form of the poem needs to be precisely controlled)
In both cases I use code fences with no syntax highlighting. I’ve used these in the past but (usually) if fixed width font isn’t needed for the form, a standard quote block is sufficient. That doesn’t give an opportunity for inline quotes (other than using standard inline quotation formats).
Obviously, I understand that there’s likely many other cases where this would come in use but maybe a more explicit example would help?
There are numerous cases where you want to separate a block of text that isn’t a blockquote, such as callouts, admonitions, examples, etc. That’s why HTML has <aside> and <section> elements. For example, you could be using markdown for an recipe blog, and you have special styling for the actual recipe. You’d need a way to mark that section so your styles could act on it. The ::: syntax is one of several proposals for this.
I agree with @jgm that it needs to be separate from code-fences. When entering a code block, you’re explicitly saying, “this area is not markdown”. Whereas ::: says, “This area is markdown, but it’s a distinct block”.
For code blocks, Markdown is agnostic to the contents. Defaulting to <pre> formatting makes sense, but the rendering environment can do additional stuff with it if it wants to, from code highlighting to execution or transformation. If the author wants to provide hints as to how it should be rendered, then a metadata block makes sense and should be standardized. There’s really no getting around the fact that you’ll need to be able to send key-value pairs to the parser for this stuff. It’s data, not text. {#id .class key="val"} is a fair option due to its flexibility.
That said, it would be of benefit to have a standard key and value to indicate “leave this as preformatted text”. For example: show=original as opposed to show=chart. If left blank, the environment chooses the default. Once standardized, a shorthand could be considered. So instead of ```{.mermaid show=original}, it could be ```mermaid:original.