This grammar implements the vimdoc "spec" (ref1, ref2). Predictable results are the primary goal, so that output formats (e.g. HTML) are well-formed; the input (vimdoc) is secondary. The first step should always be to try to fix the input rather than insist on a grammar that handles vimdoc's endless quirks.
block
is the main top-level node, delimited by blank line(s) or any line
starting with <
(codeblock terminator).
line
and line_li
nodes.line
:
h1
, h2
, h3
, column_heading
) because codeblock
terminated by "implicit stop" (no terminating <
) consumes blank lines, so
block
has no way to end.line_li
("listitem")
-
/•
(not +
/*
) are listitems.codeblock
:
line
or line_li
, because ">" can start a codeblock at the
end of any line.line
nodes without word
nodes: it's just the full raw text
line including whitespace. This is somewhat dictated by its "preformatted"
nature; parsing the contents would require loading a "child" language
(injection). See #2.<
(and any following whitespace) is discarded (anonymous).h1
= "Heading 1": ======
followed by text and optional *tags*
.h2
= "Heading 2": ------
followed by text and optional *tags*
.h3
= "Heading 3": UPPERCASE WORDS, followed by optional *tags*
, followed
by atoms.\n
). Grammar does not support files without EOL.codeblock
delimiter ">" must be preceded by a space
(" >"), not a tab. But currently the grammar doesn't enforce this. Example:
:help lcs-tab
.url
doesn't handle surrounding parens. E.g. (https://example.com/#yay)
yields word
url
doesn't handle nested parens. E.g. (https://example.com/(foo)#yay)
column_heading
currently only recognizes tilde ~
preceded by space (i.e.
foo ~
not foo~
). This covers 99% of :help files.column_heading
children should be plaintext, but currently are parsed as $._atom
.modeline
must be preceded by a blank line.tag_heading
: line(s) containing only tags, typically implies a "heading"
before a block.Steps to perform a release:
Bump and tag the version:
First bump Cargo.toml
, pyproject.toml
, and Makefile
to the new version. Then bump the package:
npm version patch -m "release %s"
Choose patch
/minor
/major
to indicate query compatibility:
patch
for bugfixes (no changes to queries needed)minor
for added nodes (queries may need changes to use new nodes but will not error)major
for removed or renamed nodes (queries will error if not adapted), other breaking changesBump to prerelease, without creating a tag:
npm version --no-git-tag-version prerelease --preid dev
git add package*.json Cargo.toml pyproject.toml Makefile
git commit -m bump
Push:
git push && git push --tags
Release the tagged commit: https://github.com/neovim/tree-sitter-vimdoc/releases/new