`tree-sitter-qmd` - grid table detection and specific errors

[rundel]

My current understanding is that grid tables will not be supported by the parser and users should migrate away via qmd-syntax-helper. If that is not the case feel free close and ignore the following.

Currently at best a grid table will parse as a sequence of paragraphs containing literal +, -, | runs. If exported as qmd the output is escaped and the grid table syntax is broken.

Alternatively, often the parser gets confused by the syntax and will throw an unrelated error due to unclosed / unpaired delimiters or other perceived issues.

Would it be possible to include a basic "detector" in the parser that identifies a block of text as a grid table, consumes the entire block without trying to further parse things and then emit a parser error specific to not supporting grid tables.

It seems reasonable to be able to recognize the +[-=+]{3,}+ opening border followed by |-delimited cell rows and the matching closing border, but I'm sure there are plenty of edge cases.

Below are a couple examples of the current parsing issues:

paragraph fallback

$ printf '%s\n' '+------+--------+' '| key  | val    |' '+------+--------+' '| a    | hello  |' '+------+--------+' | cargo run --bin pampa --
[ Para [Str "+------+--------+", SoftBreak, Str "|", Space, Str "key", Space, Str "|", Space, Str "val", Space, Str "|"],
  Para [Str "+------+--------+", SoftBreak, Str "|", Space, Str "a",   Space, Str "|", Space, Str "hello", Space, Str "|"],
  Para [Str "+------+--------+"] ]

$ printf '%s\n' '+------+--------+' '| key  | val    |' '+------+--------+' '| a    | hello  |' '+------+--------+' | cargo run --bin pampa -- -t qmd
+------+--------+
\| key \| val \|

+------+--------+
\| a \| hello \|

+------+--------+

secondary error(s)

$ printf '%s\n' '+-------------+' '| ```bash     |' '| ls -la      |' '| ```         |' '+-------------+'                           
+-------------+
| ```bash     |
| ls -la      |
| ```         |
+-------------+

$ printf '%s\n' '+-------------+' '| ```bash     |' '| ls -la      |' '| ```         |' '+-------------+' | cargo run --bin pampa --
Error: Parse error
   ╭─[ <stdin>:2:3 ]
   │
 2 │ | ```bash     |
   │   ┬
   │   ╰── unexpected character or token here
───╯
Error: Parse error
   ╭─[ <stdin>:4:3 ]
   │
 4 │ | ```         |
   │   ┬
   │   ╰── unexpected character or token here
───╯

[cscheid]

It is true that our parser will not support grid tables. It's simply not a format that lends itself well enough to good error messages.

We do have a helper application in this repo to detect grid tables and replace them with list tables (which are syntactically equally powerful and much easier to parse). That's qmd-syntax-helper.

Would it be possible to include a basic "detector" in the parser that identifies a block of text as a grid table, consumes the entire block without trying to further parse things and then emit a parser error specific to not supporting grid tables.

I'd have to study this a bit harder, but I think it would be possible at least in principle yes. We are already running an external lexer with our tree-sitter grammar. But it's actually already tricky, specifically in the presence of block quotes. There's no obvious way (to me at least) to correctly skip the chevrons of a block quote construction "inside" a grid table without actually parsing the table itself. Imagine:

simple:

> +----+
> | oh |
> +----+

hellish:

> > +----+
> > | oh |
> > +----+
> | pipe-table-now |
> |-|
> | no |
> > +----+
> > | no |
> > +----+

I hesitate to jump into putting this on the official parser itself because people will start depending on the behavior, and that's why we did qmd-syntax-helper, which is by design a best-effort tool.

[rundel]

I played around a bit with this in claude code this evening just to see if it might be possible - everything that follows is purely a proof of concept and not an implementation that I endorse in anyway. It is all purely vibe coded and I have not reviewed any of the implementation details or code (I do not know anything beyond the most basic bits of treesitter and rust). Testing is not extensive but I didn't break anything obvious as far as I can tell.

The code is available at https://github.com/rundel/q2/tree/feature/grid-table-error ,

Sample output looks like:

Fixture 1: bare grid tables (no block quote)

gt_block_quote1.qmd:

+----+
| oh |
+----+

+------+--------+
| key  | val    |
+------+--------+
| a    | hello  |
+------+--------+

+-------------+
| ```bash     |
| ls -la      |
| ```         |
+-------------+

```
+----+
| oh |
+----+
```

Run:

cargo run --bin q2 -- render gt_block_quote/gt_block_quote1.qmd

Output:

Error: [Q-2-36] Grid tables are not supported
   ╭─[ gt_block_quote1.qmd:1:1 ]
   │
 1 │ ╭─▶ +----+
 2 │ │   | oh |
 3 │ ├─▶ +----+
   │ │
   │ ╰──────────── Grid tables aren't supported. Use a pipe table instead.
───╯

Error: [Q-2-36] Grid tables are not supported
   ╭─[ gt_block_quote1.qmd:5:1 ]
   │
 5 │ ╭─▶ +------+--------+
 6 │ │   | key  | val    |
 7 │ │   +------+--------+
 8 │ │   | a    | hello  |
 9 │ ├─▶ +------+--------+
   │ │
   │ ╰─────────────────────── Grid tables aren't supported. Use a pipe table instead.
───╯

Error: [Q-2-36] Grid tables are not supported
    ╭─[ gt_block_quote1.qmd:11:1 ]
    │
 11 │ ╭─▶ +-------------+
 12 │ │   | ```bash     |
 13 │ │   | ls -la      |
 14 │ │   | ```         |
 15 │ ├─▶ +-------------+
    │ │
    │ ╰───────────────────── Grid tables aren't supported. Use a pipe table instead.
────╯

(Note: the trailing fenced code block in the source — lines ~17–21 — is not flagged. Content inside ``` fences is treated as a code block, so +----+ / | oh | lines there don't trigger the grid-table detector. This is the correct behavior.)

---

Fixture 2: grid table inside a single block quote

gt_block_quote2.qmd:

> +----+
> | oh |
> +----+

Run:

cargo run --bin q2 -- render gt_block_quote/gt_block_quote2.qmd

Output:

Error: [Q-2-36] Grid tables are not supported
   ╭─[ gt_block_quote2.qmd:1:3 ]
   │
 1 │ ╭─▶ > +----+
 2 │ │   > | oh |
 3 │ ├─▶ > +----+
   │ │
   │ ╰────────────── Grid tables aren't supported. Use a pipe table instead.
───╯

---

Fixture 3: nested block quotes with intermediate non-grid lines

gt_block_quote3.qmd:

> > +----+
> > | oh |
> > +----+
> | pipe-table-now |
> |-|
> | no |
> > +----+
> > | no |
> > +----+

Run:

cargo run --bin q2 -- render gt_block_quote/gt_block_quote3.qmd

Output:

Error: [Q-2-36] Grid tables are not supported
   ╭─[ gt_block_quote3.qmd:1:5 ]
   │
 1 │ ╭─▶ > > +----+
 2 │ │   > > | oh |
 3 │ ├─▶ > > +----+
   │ │
   │ ╰──────────────── Grid tables aren't supported. Use a pipe table instead.
───╯

Error: [Q-2-36] Grid tables are not supported
   ╭─[ gt_block_quote3.qmd:7:5 ]
   │
 7 │ ╭─▶ > > +----+
 8 │ │   > > | no |
 9 │ ├─▶ > > +----+
   │ │
   │ ╰──────────────── Grid tables aren't supported. Use a pipe table instead.
───╯

[cscheid]

Amazing! I would definitely be willing to look at a PR for this. Thank you!