From df34580aae3c836b2032fad6c3cb44d9b180cd67 Mon Sep 17 00:00:00 2001
From: Austin Horstman <khaneliman12@gmail.com>
Date: Thu, 25 Jun 2026 14:57:39 -0500
Subject: [PATCH] doc/neovim: document WASM treesitter parsers

Show how to use the existing wasi32 cross parser set with
wasm-enabled Neovim, and explain why native and WASM parsers
should not be mixed for one language.
---
 doc/languages-frameworks/neovim.section.md | 37 ++++++++++++++++++++++
 doc/redirects.json                         |  3 ++
 2 files changed, 40 insertions(+)

diff --git a/doc/languages-frameworks/neovim.section.md b/doc/languages-frameworks/neovim.section.md
index b131e65a0e59..e0c22d8ccba5 100644
--- a/doc/languages-frameworks/neovim.section.md
+++ b/doc/languages-frameworks/neovim.section.md
@@ -248,6 +248,43 @@ You can install the standalone parsers and queries directly without installing `
 })
 ```
 
+### Treesitter setup using WASM parsers and queries {#neovim-plugin-treesitter-wasm}
+
+Neovim can load WASM parsers when it is built with Wasmtime support.
+In nixpkgs, WASM parser plugins are available from the `wasi32` cross package set:
+
+```nix
+(pkgs.wrapNeovim (pkgs.neovim-unwrapped.override { wasmSupport = true; }) {
+  configure = {
+    packages.myPlugins =
+      with pkgs.pkgsCross.wasi32.vimPlugins;
+      let
+        # Select the grammars you need
+        treesitter-grammars = with nvim-treesitter-parsers; [
+          nix
+          python
+        ];
+        # Queries are needed for treesitter based syntax highlighting and folds.
+        treesitter-queries = map (p: p.associatedQuery) treesitter-grammars;
+      in
+      {
+        start = [
+          # regular plugins
+        ]
+        ++ treesitter-grammars
+        ++ treesitter-queries;
+      };
+  };
+})
+```
+
+Do not install both native and WASM parsers for the same language.
+For example, installing both `pkgs.vimPlugins.nvim-treesitter-parsers.nix` and
+`pkgs.pkgsCross.wasi32.vimPlugins.nvim-treesitter-parsers.nix` is invalid because Neovim
+loads the first `parser/nix.*` found on `runtimepath`.
+
+Use `:checkhealth vim.treesitter` to verify Nix-managed WASM parsers.
+
 You can enable treesitter features for installed grammars in a `FileType` autocommand
 or in an `ftplugin/<language>.lua` script, e.g.
 
diff --git a/doc/redirects.json b/doc/redirects.json
index 992e6cfcac87..cf6ab6a33842 100644
--- a/doc/redirects.json
+++ b/doc/redirects.json
@@ -224,6 +224,9 @@
   "neovim-luarocks-based-plugins": [
     "index.html#neovim-luarocks-based-plugins"
   ],
+  "neovim-plugin-treesitter-wasm": [
+    "index.html#neovim-plugin-treesitter-wasm"
+  ],
   "nixpkgs-manual": [
     "index.html#nixpkgs-manual"
   ],