Quarto visual mode / source mode switching breaks equation block formatting and syntax highlighting

[Vara326]

Bug description

👋hello! This issue was originally posted at posit-dev/positron#14763 (comment), and is reposted here at the request of @juliasilge .

When switching between visual mode and source mode in a Quarto .qmd document, the editor reformats multi-line equation blocks

$$
equation
$$

into single-line form

$$equation$$

, which causes two related bugs:

Bug 1 — Cross-reference label malformation

After a visual→source mode switch, a properly formatted numbered equation like:

$$
y_i = \alpha + \sum_{j=1}^{p} \beta_j x_{ij} + \varepsilon_i
$$ {#eq-liner-model}

is reformatted into:

$$\text{equation}$$
 {#eq-a-error-format}

The label {#eq-a-error-format} is placed on a new line with a leading space, making it unrecognizable to the Quarto cross-reference engine. Rendering the document produces:

Unable to resolve crossref @eq-a-error-format

Bug 2 — Lost syntax highlighting (gray background)

A correctly formatted single-line numbered equation:

$$(\hat{\alpha}, \hat{\boldsymbol{\beta}}) = \arg\min \left\{ \sum_{i=1}^{N} \left(y_i - \alpha - \sum_{j=1}^{p} \beta_j x_{ij}\right)^2 \right\} \quad \text{subject to} \quad \sum_{j=1}^{p} |\beta_j| \leq t$$ {#eq-lasso}

renders correctly and cross-references work, but the equation block itself is not wrapped in the usual gray background box. Moreover, any R code blocks that follow this equation also lose their gray background.

Expected behavior:

Switching between visual and source mode should preserve the original multi-line equation block structure.

The {#eq-label} syntax should remain on the same line as the closing $$.

All code blocks should consistently display the gray background regardless of preceding equation formatting.

I have checked posit-dev/positron#8684 (comment). It seems to be related to the issue I am experiencing, but it looks like it has not been properly fixed yet.

My Quarto version is 1.9.38 and my Positron version is 2026.07.0.

Attachments:

[Vara326]

I'd like to add that after the gray background of the R code chunk disappears, the outline view seems unable to correctly recognize the label of the R code chunk.

This is normal:

After the gray background of the R code chunk disappears:

By comparison, the first R code block always has a gray background. However, after a formula's gray background (here {#eq-lasso}) has problems, all code blocks following this formula will lose their gray background.

[Vara326]

I've discovered a new issue, also related to visual mode / source mode switching. When switching from visual mode to source mode, the qmd file undergoes automatic formatting, but this formatting tends to collapse display math blocks, removing the newlines after and before the $$ delimiters. In this case, my formula was a multi-line mathematical expression, and I suspect that in some cases Pandoc requires the $$ delimiters for display math to occupy their own lines, which the current formatting ignores.

The following format is correct:

$$
\begin{gather*}
a_{kl} = |X_k - X_l|_p, \quad A_{kl} = a_{kl} - \bar{a}_{k\cdot} - \bar{a}_{\cdot l} + \bar{a}_{\cdot\cdot} \\
b_{kl} = |Y_k - Y_l|_q, \quad B_{kl} = b_{kl} - \bar{b}_{k\cdot} - \bar{b}_{\cdot l} + \bar{b}_{\cdot\cdot}
\end{gather*}
$$

But after switching from visual mode to source mode, it will be formatted as

$$\begin{gather*}
a_{kl} = |X_k - X_l|_p, \quad A_{kl} = a_{kl} - \bar{a}_{k\cdot} - \bar{a}_{\cdot l} + \bar{a}_{\cdot\cdot} \\
b_{kl} = |Y_k - Y_l|_q, \quad B_{kl} = b_{kl} - \bar{b}_{k\cdot} - \bar{b}_{\cdot l} + \bar{b}_{\cdot\cdot}
\end{gather*}$$

When rendered and previewed, it displays correctly, but this format confuses positron. Similarly, the gray background of code blocks and formulas disappears, and positron will not recognize subsequent headings. QUARTO:EQUATION will also fail to preview this formula:

The expected behavior should be as follows:

As the number of mathematical formulas written in qmd files increases, manually fixing these errors after switching from visual mode to source mode becomes increasingly troublesome.

I personally suggest that the short-term solution is to ensure that formula blocks always remain in multi-line format when transitioning from visual mode to source mode.

$$
formula
$$

[volumen25]

I have a similar problem with LaTeX when switching to the Visual Editor

37.5\%	

becomes

37.5%

Likewise, a table identifier:

: Examples of process variables {#tbl-process-variables}

becomes

: Examples of process variables

more details here