# Proposal to relax fenced blocks definition **URL:** \ **Category:** Extensions\ **Created:** [February 11, 2022, 12:48am UTC](https://talk.commonmark.org/t/proposal-to-relax-fenced-blocks-definition/4088 "2022-02-11T00:48:44Z")\ **Posts on this page:** 13\ **Page:** 1
**Author:** ![vitaly](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/vitaly/32/396_2.png) [@vitaly](https://talk.commonmark.org/u/vitaly)\ **Post date:** [February 11, 2022, 12:48am UTC](https://talk.commonmark.org/t/proposal-to-relax-fenced-blocks-definition/4088/1 "2022-02-11T00:48:44Z")
Ref: [Mermaid - Generation of diagrams and flowcharts from text in a similar manner as markdown - #48 by vitaly](https://talk.commonmark.org/t/mermaid-generation-of-diagrams-and-flowcharts-from-text-in-a-similar-manner-as-markdown/1882/48) Currently, fenced blocks are described as “for code only”. But, there are real world use cases, which require markup with the same principle. 1. Diagrams (text description + special renderer) - Isolated self-sufficient content 2. Quotes - Wrapper with some attributes for inner markdown. Both cases are very well known. Example - Discourse. IMO, inventing alternate guards instead of “```” does not provide any benefits. I suggest to relax fenced block definition: - Say, “extensions can use custom renderer” (and even allow markdown inside) - Give recommendation for info string format (to pass params) ---
**Author:** ![jgm](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/jgm/32/1360_2.png) [@jgm](https://talk.commonmark.org/u/jgm)\ **Post date:** [February 11, 2022, 2:04am UTC](https://talk.commonmark.org/t/proposal-to-relax-fenced-blocks-definition/4088/2 "2022-02-11T02:04:36Z")
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. ---
**Author:** ![vitaly](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/vitaly/32/396_2.png) [@vitaly](https://talk.commonmark.org/u/vitaly)\ **Post date:** [February 11, 2022, 2:46am UTC](https://talk.commonmark.org/t/proposal-to-relax-fenced-blocks-definition/4088/3 "2022-02-11T02:46:11Z")
Hm… thanks, that means, diagrams should be fine, and only info string format should be recommended, to unify different extensions look. > [@jgm](#): > > 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. 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”. ---
**Author:** ![vitaly](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/vitaly/32/396_2.png) [@vitaly](https://talk.commonmark.org/u/vitaly)\ **Post date:** [February 11, 2022, 10:07am UTC](https://talk.commonmark.org/t/proposal-to-relax-fenced-blocks-definition/4088/4 "2022-02-11T10:07:28Z")
I try to express my thoughts in different words. 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: 1. Consider those as exclusions for existing fenced blocks markup 2. Create new guard `:::` for such blocks 3. 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). ---
**Author:** ![vas](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/vas/32/1267_2.png) [@vas](https://talk.commonmark.org/u/vas)\ **Post date:** [February 11, 2022, 4:54pm UTC](https://talk.commonmark.org/t/proposal-to-relax-fenced-blocks-definition/4088/5 "2022-02-11T16:54:50Z")
> [@jgm](#): > > 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. 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: ````auto ``` mermaid ! diagram code here ``` ```` then per logical consistency it should be ok to graphically render the formatted text doc described in this block: ````auto ``` rst ! reStructuredText code here ``` ```` and likewise for this block: ````auto ``` 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. ---
**Author:** ![jgm](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/jgm/32/1360_2.png) [@jgm](https://talk.commonmark.org/u/jgm)\ **Post date:** [February 11, 2022, 9:32pm UTC](https://talk.commonmark.org/t/proposal-to-relax-fenced-blocks-definition/4088/6 "2022-02-11T21:32:08Z")
> We can: > > 1. Consider those as exclusions for existing fenced blocks markup > 2. Create new guard `:::` for such blocks > 3. 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.). ---
**Author:** ![vitaly](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/vitaly/32/396_2.png) [@vitaly](https://talk.commonmark.org/u/vitaly)\ **Post date:** [February 11, 2022, 11:18pm UTC](https://talk.commonmark.org/t/proposal-to-relax-fenced-blocks-definition/4088/7 "2022-02-11T23:18:38Z")
If you prefer `:::` for “quotes”, what to do with “notes”, “asides” and other nestable containers? We can not invent unique guard for every case. > [@jgm](#): > > People > write in lots of languages other than English, and it’s awkward > and unmarkdownish to use English words to indicate structure. 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. ---
**Author:** ![jgm](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/jgm/32/1360_2.png) [@jgm](https://talk.commonmark.org/u/jgm)\ **Post date:** [February 12, 2022, 12:26am UTC](https://talk.commonmark.org/t/proposal-to-relax-fenced-blocks-definition/4088/8 "2022-02-12T00:26:47Z")
Vitaly Puzrin via CommonMark Discussion [noreply@talk.commonmark.org](mailto:noreply@talk.commonmark.org) writes: > 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: 1. a generic container for literal inline text 2. a generic container for parsed inlines 3. a generic container for literal blocks 4. 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. In pandoc, these can be done with: ````auto 1. `literal text`{#id .class key="val"} 2. [inline *text*]{#id .class key="val"} 3. ``` {#id .class key="val"} literal block ``` 4. ::: {#id .class key="val"} - parsed - *block* ::: ```` > 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. ---
**Author:** ![vitaly](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/vitaly/32/396_2.png) [@vitaly](https://talk.commonmark.org/u/vitaly)\ **Post date:** [February 12, 2022, 1:36am UTC](https://talk.commonmark.org/t/proposal-to-relax-fenced-blocks-definition/4088/9 "2022-02-12T01:36:57Z")
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). > [@jgm](#): > > These don’t affect parsing/structure. They’re part of the > content, not the form. I understand the difference. I don’t understand why english words in structure will be a problem for users. ---
**Author:** ![jgm](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/jgm/32/1360_2.png) [@jgm](https://talk.commonmark.org/u/jgm)\ **Post date:** [February 12, 2022, 3:18am UTC](https://talk.commonmark.org/t/proposal-to-relax-fenced-blocks-definition/4088/10 "2022-02-12T03:18:08Z")
I don’t think that ```auto ::: aside my quote ::: ``` is any uglier than ````auto ``` aside my quote ``` ```` (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. ---
**Author:** ![vitaly](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/vitaly/32/396_2.png) [@vitaly](https://talk.commonmark.org/u/vitaly)\ **Post date:** [February 12, 2022, 4:40am UTC](https://talk.commonmark.org/t/proposal-to-relax-fenced-blocks-definition/4088/11 "2022-02-12T04:40:58Z")
> [@jgm](#): > > I don’t think that > > ```auto > ::: aside > my quote > ::: > > ``` > > is any uglier than > > ````auto > ``` aside > my quote > ``` > > ```` > > (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. 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. > [@jgm](#): > > 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 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.` ---
**Author:** ![Catija](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/catija/32/2164_2.png) [@Catija](https://talk.commonmark.org/u/Catija)\ **Post date:** [February 17, 2022, 2:51pm UTC](https://talk.commonmark.org/t/proposal-to-relax-fenced-blocks-definition/4088/12 "2022-02-17T14:51:35Z")
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? ---
**Author:** ![Trillinon](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/trillinon/32/1055_2.png) [@Trillinon](https://talk.commonmark.org/u/Trillinon)\ **Post date:** [February 17, 2022, 6:46pm UTC](https://talk.commonmark.org/t/proposal-to-relax-fenced-blocks-definition/4088/13 "2022-02-17T18:46:13Z")
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 `