Add visual support (like folding, colorisation of matching open-close, navigation, ...) for fenced div syntax (`:::`)

[mcanouil]

• https://code.visualstudio.com/api/language-extensions/language-configuration-guide

Current "workaround" at least for the paired colorisation:

"editor.guides.bracketPairs": "active",
"editor.language.brackets": [
  ["[", "]"],
  ["(", ")"],
  ["{", "}"],
  ["::::", ":::"]
],
"editor.language.colorizedBracketPairs": [
  ["[", "]"],
  ["(", ")"],
  ["{", "}"],
  ["::::", ":::"]
],

[fretwurst]

Thank you very much for the hint and the workaround. However, it doesn’t work on my end — or rather, I meant something slightly different. The colorisation of div in your workaround assigns a different color to each new ::: . That doesn’t really help with identifying matching pairs, and in the worst case, it might even be counterproductive, right? I think it would be more helpful for identifying corresponding start and end ::: if they were given the same color. Unmatched or misplaced ::: could be highlighted in grey or red, or something similar, to make them easier to spot.

[mcanouil]

Pandoc does not care about matching pairs.
And a workaround is a workaround not the solution.

Note that the trick mentioned is based on real usage of fenced divs.

[fretwurst]

With the following very simple example, multiple ::: end up in the output documents (HTML and PDF). In this simplified example, you can still spot the leftover ::: lines that weren't properly removed. In more complex documents, that’s no longer that easy. Even though Pandoc doesn’t care about matching pairs, these ::: lines cause issues—especially when they once belonged to a longer div that has since become orphaned.

That’s why I requested a feature to visually highlight "matching" ::: pairs in the editor. A workaround that simply gives each ::: a different color does not solve this problem—since it doesn't work to identify matching or broken pairs—it isn't working and so, from my point of view, it isn't a workaround.

But all right, now my feature request has been closed as a duplicate of a two-year-old workaround. So I’ll just let it go. :-)

---
title: "Untitled"
format: 
    html: 
        section-divs: true
    pdf: 
        toc: true
---

# Header 1

:::: {.columns}
::: {.column width="50%"}

::: {.callout}
#### Callout
Warning
:::
:::

:::: {.column width="50%"}
::: {.callout-warning}
## Warning
Warning
:::
:::
::::

:::

::: {.callout}
### Something else

Text
:::
::::

[mcanouil]

But all right, now my feature request has been closed as a duplicate of a three-year-old workaround. So I’ll just let it go.

I think you are mistaken on what is happening here.

The issue here is the same feature request as you but in addition to asking for this, it provides a workaround while waiting for an implementation of something "better".

[cderv]

But all right, now my feature request has been closed as a duplicate of a two-year-old workaround. So I’ll just let it go. :-)

@fretwurst, as the one who closed your issue as a duplicate, let me confirm the reply above.

This issue is a feature request to add colorization for Fenced Div, and it is a good feature request. By the way, it is not two years old but was opened this year. We'll get to it, but this is not a trivial enhancement, and we do our best to work with a small team on both Quarto CLI and Quarto VS CODE extensions. Rest assured that we prioritized at our best, and we won't forget this. Closing issues as duplicates helps us centralize everything in one place.

Thank you for your understanding, and sorry for not having detailed the reason for my closing. I probably should have.

[cscheid]

@fretwurst What's happening is that your markdown has syntax problems. I'll explain in full below.

That’s why I requested a feature to visually highlight "matching" ::: pairs in the editor. A workaround that simply gives each ::: a different color does not solve this problem

You're getting different colors because in your documents they really appear to be mismatched, because of the syntax issues.

Let's send your markdown through Pandoc directly:

$ pandoc -f markdown -t native
# Header 1

:::: {.columns}
::: {.column width="50%"}

::: {.callout}
#### Callout
Warning
:::
:::

:::: {.column width="50%"}
::: {.callout-warning}
## Warning
Warning
:::
:::
::::

:::

::: {.callout}
### Something else

Text
:::
::::
^D
[ Header
    1
    ( "header-1" , [] , [] )
    [ Str "Header" , Space , Str "1" ]
, Div
    ( "" , [ "columns" ] , [] )
    [ Div
        ( "" , [ "column" ] , [ ( "width" , "50%" ) ] )
        [ Div
            ( "" , [ "callout" ] , [] )
            [ Header 4 ( "callout" , [] , [] ) [ Str "Callout" ]
            , Para [ Str "Warning" ]
            ]
        ]
    , Div
        ( "" , [ "column" ] , [ ( "width" , "50%" ) ] )
        [ Div
            ( "" , [ "callout-warning" ] , [] )
            [ Header 2 ( "warning" , [] , [] ) [ Str "Warning" ]
            , Para [ Str "Warning" ]
            ]
        ]
    ]
, Para [ Str ":::" ]
, Div
    ( "" , [ "callout" ] , [] )
    [ Header
        3
        ( "something-else" , [] , [] )
        [ Str "Something" , Space , Str "else" ]
    , Para [ Str "Text" ]
    ]
, Para [ Str "::::" ]
]

Note the Para [ Str ":::" ] entries: this is Pandoc telling you that it thinks you wrote a paragraph with ::: in it, instead of a fenced div marker.

Our goal then is to figure out where the error is. Before we get to it, I'll note what I believe to be a serious design mistake with Commonmark (the Markdown specification used by Pandoc). In Commonmark, there are no syntax errors: every single sequence of characters is a valid Commonmark document. This makes it fundamentally impossible for Quarto to tell you where the divs are mismatched (because in a sense, they never can really be mismatched; they just become Para [ Str ":::" ] instead. Of course, you and most users almost certainly never mean to write a paragraph with :::, which is why I claim this to be a serious design mistake). I note this because we have a plan to rectify this situation in Quarto, by providing a separate Markdown parser that will give you syntax errors instead.

Back to figuring out the error. I find it helpful to create a div structure where the outer divs have more colons than the ones inside it to make it easier to find the matching div. When you do that, you will notice that you have an opening div marker without the required class specifier or {}. That's the triple colon before the last callout. If you add a {} to that line, you'll see that the problem goes away.

I think you're getting confused by a few (admittedly strange) quirks of Pandoc's fenced div notation:

• When you start a fenced div, it needs to either have a {} marker or a class specifier. So, these is valid:

  ::: {}
  My div contents
  :::
  
  ::: a-class
  My div contents
  :::
  
  ::: {#an-id .a-class}
  My div contents
  :::
  

  But this isn't valid:

  :::
  My bad div contents.
  :::
  

• A fenced div doesn't need to have the same number of colons on their opening and closing markers. It's visually helpful for them to be the same, but the syntax doesn't require. The following are all equivalent:

  ::::: {}
  A div
  :::
  
  ::: {}
  A div
  ::::::::
  
  ::: {}
  A div
  :::
  
  

If you use my recommendations (spaces between divs, matching number of colons), then your document would have looked like this:

# Header 1

::::: {.columns}

:::: {.column width="50%"}

::: {.callout}

#### Callout

Warning

:::

::::

:::: {.column width="50%"}

::: {.callout-warning}

## Warning

Warning

:::

:::: 

:::::

:::: <-- your bug

::: {.callout}

### Something else

Text

:::

::::

Here, I would argue that it's more obvious that you have an opening div (that I've annotated above with "your bug") that is missing the required {} specifier.

I hope this helps.

[fretwurst]

@cderv Thank you very much for the clarification — and you're right, I misread the date and thought the issue was older (Feb 2023) than it actually is. That’s on me — and I appreciate the correction.

It’s good to know that this feature is on your radar. My concern was mainly that the inclusion of a workaround — even if well-intended — can sometimes give the impression that the problem is “good enough for now,” even when the workaround doesn’t really solve the issue (and in this case, might even make matching harder).

I completely understand that you need to prioritize and consolidate similar requests, especially with limited resources. Thanks again for your thoughtful reply and for all the work you’re putting into Quarto — it’s a fantastic tool, and I know many of us are deeply grateful for it.

[fretwurst]

@cscheid Thank you very much for your detailed explanation and the time you took to analyze this!

Just to clarify: I deliberately introduced the syntax bugs into the document to demonstrate that mismatched ::: pairs do cause issues—namely, that they appear in the rendered output. This was in response to mcanouil’s claim that “Pandoc does not care about matching pairs.”

My main point is that the workaround of randomly color-coding all ::: lines isn’t helpful in this case. In the corrected version of the document you shared, the color pairing still looks like what I show here—so from a user’s perspective, it's not actually solving the underlying issue:

As an end user (not a developer), I don’t fully grasp everything you described about the design flaw in Pandoc/CommonMark, but I believe I understood the core idea: since ::: blocks don’t have an unambiguous start and end like parentheses or brackets, this leads to real-world problems when writing or debugging documents. And I agree—if we had clear opening and closing markers, I probably could have hacked together an working extension-based workaround myself. :-)

[fretwurst]

@mcanouil Thanks again for your earlier replies — I went back and re-read everything, and now I finally understand what was going on.

I had overlooked the fact that for your workaround to work, the opening and closing delimiters must follow a specific pattern: exactly four colons (::::) to open, and exactly three (:::) to close. That detail wasn't obvious to me at first (especially since it’s easy to miss visually), and in my initial examples I had mistakenly used ::: for both opening and closing — which, of course, prevented the colorised pairing from working at all.

So yes — the workaround does work, and I appreciate that you pointed it out early on. My misunderstanding was based on incorrect usage, not on the workaround itself.

And yes: “a workaround is a workaround, not the solution.” That’s why I’d still appreciate if the feature request could remain open. The workaround doesn't support Carlos helpful suggestion to use more colons for outer divs, which is often useful for readability in nested structures.

For clarity, I’ve included below a minimal working example (now correctly formatted) and a screenshot of the same structure in Positron, showing the colorized brackets as intended.

Thanks again for your patience — and for helping me get this straight.
Below is a corrected example and a screenshot showing the bracket coloring in action.

# Header 1

:::: {.content-visible when-format='html'}

:::: {.columns}
:::: {.column width="50%"}

:::: {.callout}
#### Callout

Warning
:::
:::
:::

:::: {.column width="50%"}

:::: {.callout-warning}
## Warning

Warning
:::
:::

:::: {.callout}
### Something else

Text
:::
:::

[mcanouil]

That’s why I’d still appreciate if the feature request could remain open

Again, this issue is the same thing that you requested, i.e., a way to have colours, folding, etc. for divs.
The implementation either using asymmetric or surnumerous colons is up to the devs in accordance with many things in particular the Visual Editor which uses Pandoc to normalise the syntax.

[fretwurst]

OK