quarto-dev / quarto-dev/quarto

Feature request: Add syntax highlighting for \begin{equation}, \begin{align}, and \[...\] in .qmd files

Open Beginner friendly
#934 1 comment 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

vscode
Dominant language
TypeScript
Stars
645
Forks
62
Avg merge
17h 42m
Merged PRs (30d)
13

Description

Description

The Quarto VS Code extension's TextMate grammar currently only recognizes $...$ (inline) and $$...$$ (display) as math scopes in .qmd files. LaTeX math environments like \begin{equation}, \begin{align}, and \[...\] receive no math highlighting, even though they are valid and commonly used in Quarto documents — especially in math-heavy academic papers.

Current behaviour

In a .qmd file:

  • $x^2$ → highlighted as math ✅
  • $$x^2$$ → highlighted as math ✅
  • \begin{equation} x^2 \end{equation} → no highlighting ❌
  • \begin{align} x^2 \end{align} → no highlighting ❌
  • \[ x^2 \] → no highlighting ❌
Proposed solution

Add begin/end rules to quarto.tmLanguage.yaml for LaTeX math environments, scoped as markup.math.block.quarto with meta.embedded.math.quarto content — identical to how $$ blocks are handled. The change is small (~20 lines of YAML):

math_environment:
  name: markup.math.block.quarto
  contentName: meta.embedded.math.quarto
  begin: '(\\begin\{(equation|align|alignat|gather|multline|flalign|split|aligned|gathered|multlined)\*?\})'
  beginCaptures:
    '1':
      name: keyword.control.import.math.begin.quarto
  end: '(\\end\{\2\*?\})'
  endCaptures:
    '1':
      name: keyword.control.import.math.end.quarto
  patterns:
    - {include: 'text.html.markdown.math#math'}

math_display_delim:
  name: markup.math.block.quarto
  contentName: meta.embedded.math.quarto
  begin: '(\\\[)'
  beginCaptures:
    '1':
      name: keyword.control.import.math.begin.quarto
  end: '(\\\])'
  endCaptures:
    '1':
      name: keyword.control.import.math.end.quarto
  patterns:
    - {include: 'text.html.markdown.math#math'}

These rules would be added to the repository section of the grammar and included in the block patterns before math_block.

Use case

I write computational statistics papers in Quarto using \begin{equation}, \begin{align}, and custom theorem environments. The lack of math highlighting for these standard LaTeX environments makes the editing experience significantly worse compared to pure .tex files, especially for equation-heavy documents. This is likely a common pain point for anyone using Quarto for academic writing.

Happy to submit a PR if that would be helpful.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Open quarto.tmLanguage.yaml and review the repository rules and block patterns around math_block. Add coverage for the listed LaTeX environments and [...] delimiters, then verify that equation, align, and display-delimited math receive the stated scopes in .qmd files.

Written by the indexing model from the issue text.

Assessment

Tech stack
yaml
Domain
tooling
Issue type
Feature
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.