math-conceal.nvim ☀️

中文版文档：zh-cn

Faster and More Precise LaTeX and typst conceal for Neovim.

2026-01-07.15.13.10.mov

LaTeX-Before

LaTeX-After

Introduction

In neovim 0.11.0, the treesitter query has been changed to allow the asynchronous query, which allows us to use the treesitter query to conceal latex file. However, it's still slow while fully use #set! conceal directive since the expansive cost of query over the whole AST while conceal a single node.

The basic solution of the problem above comes from latex.nvim, who uses customized set-pairs directive to conceal the latex file. However, it still has some performance problem. The way to resolve the performance issue is considering a hash map to accelerate pattern matching, instead of matching conceal pattern inside AST query file. Using a proper-designed lua module to handle the conceal patterns and only use treesitter to locate the position of the patterns can significantly improve the performance of conceal.

Features

• High performance conceal for LaTeX and typst files.
• Fine grained conceal patterns:
  • Original neovim conceal patterns: expand all concealed nodes on the line where the cursor is located.
  • Fine grained conceal patterns: only expand the concealed node under the cursor.
• Support multiple conceal patterns, including greek letters, script letters, math symbols, font styles, delimiters, and physical units.
• Multiple highlight groups for different conceal patterns, allowing you to customize the appearance of each pattern (all highlight groups can be found in highlights).

Installation

rocks.nvim

Command style

:Rocks install math-conceal.nvim

Declare style

~/.config/nvim/rocks.toml:

[plugins]
"math-conceal.nvim" = "scm"

Then

:Rocks sync

or:

$ luarocks --lua-version 5.1 --local --tree ~/.local/share/nvim/rocks install math-conceal.nvim
# ~/.local/share/nvim/rocks is the default rocks tree path
# you can change it according to your vim.g.rocks_nvim.rocks_path

lazy.nvim

return {
  "pxwg/math-conceal.nvim",
  event = "VeryLazy",
  main = "math-conceal",
  --- @type LaTeXConcealOptions
  opts = {
    conceal = {
      "greek",
      "script",
      "math",
      "font",
      "delim",
      "phy",
    },
    ft = { "plaintex", "tex", "context", "bibtex", "markdown", "typst" },
  },
}

To-do

• Better support for typst files, and customizable conceal patterns.
  • LaTeX customizable conceal patterns.
  • Typst customizable conceal patterns.
• Commutative diagram conceal for Typst files.
• Table conceal for LaTeX and Typst files (inspired from render-markdown.nvim).
• Automatically maintain the conceal query file and math_symbols.json file.
  • Typst
  • LaTeX

References

• ts_query_lsp I use this LSP as a pre-commit hook to format the query file.
• latex_concealer.nvim for some ideas about conceal patterns.

Acknowledgements

• Freed-Wu: Instrumental in publishing this plugin to LuaRocks and refactoring the code structure to fit the best practices for Neovim plugins.
• Dirichy: for helpful discussions about LaTeX conceal patterns and optimizations.
• latex.nvim for the idea of using customized conceal patterns.
• latex_concealer.nvim for the idea of fine grained conceal patterns.