docs: migrate to mdbook

docs/src/cli/build.md

@@ -0,0 +1,43 @@
+# `tree-sitter build`
+
+The `build` command compiles your parser into a dynamically-loadable library,
+either as a shared object (`.so`, `.dylib`, or `.dll`) or as a WASM module.
+
+```bash
+tree-sitter build [OPTIONS] [PATH] # Aliases: b
+```
+
+You can change the compiler executable via the `CC` environment variable and add extra flags via `CFLAGS`.
+For macOS or iOS, you can set `MACOSX_DEPLOYMENT_TARGET` or `IPHONEOS_DEPLOYMENT_TARGET` respectively to define the
+minimum supported version.
+
+The path argument allows you to specify the directory of the parser to build. If you don't supply this argument, the CLI
+will attempt to build the parser in the current working directory.
+
+## Options
+
+### `-w/--wasm`
+
+Compile the parser as a WASM module.
+
+### `-d/--docker`
+
+Use Docker or Podman to supply Emscripten. This removes the need to install Emscripten on your machine locally.
+Note that this flag is only available when compiling to WASM.
+
+### `-o/--output`
+
+Specify where to output the shared object file (native or WASM). This flag accepts either an absolute path or a relative
+path. If you don't supply this flag, the CLI will attempt to figure out what the language name is based on the parent
+directory name to use for the output file. If the CLI can't figure it out, it will default to `parser`, thus generating
+`parser.so` or `parser.wasm` in the current working directory.
+
+### `--reuse-allocator`
+
+Reuse the allocator that's set in the core library for the parser's external scanner. This is useful in applications
+where the author overrides the default allocator with their own, and wants to ensure every parser that allocates memory
+in the external scanner does so using their allocator.
+
+### `-0/--debug`
+
+Compile the parser with debug flags enabled. This is useful when debugging issues that require a debugger like `gdb` or `lldb`.

docs/src/cli/complete.md

@@ -0,0 +1,16 @@
+# `tree-sitter complete`
+
+The `complete` command generates a completion script for your shell.
+This script can be used to enable autocompletion for the `tree-sitter` CLI.
+
+```bash
+tree-sitter complete --shell <SHELL> # Aliases: comp
+```
+
+## Options
+
+### `--shell <SHELL>`
+
+The shell for which to generate the completion script.
+
+Supported values: `bash`, `elvish`, `fish`, `power-shell`, `zsh`, and `nushell`.

docs/src/cli/dump-languages.md

@@ -0,0 +1,15 @@
+# `tree-sitter dump-languages`
+
+The `dump-languages` command prints out a list of all the languages that the CLI knows about. This can be useful for debugging purposes, or for scripting. The paths to search comes from the config file's [`parser-directories`][parser-directories] object.
+
+```bash
+tree-sitter dump-languages [OPTIONS] # Aliases: langs
+```
+
+## Options
+
+### `--config-path`
+
+The path to the configuration file. Ordinarily, the CLI will use the default location as explained in the [init-config](./init-config.md) command. This flag allows you to explicitly override that default, and use a config defined elsewhere.
+
+[parser-directories]: ./init-config.md#parser-directories

docs/src/cli/fuzz.md

@@ -0,0 +1,49 @@
+# `tree-sitter fuzz`
+
+The `fuzz` command is used to fuzz a parser by performing random edits and ensuring that undoing these edits results in
+consistent parse trees. It will fail if the parse trees are not equal, or if the changed ranges are inconsistent.
+
+```bash
+tree-sitter fuzz [OPTIONS] # Aliases: f
+```
+
+## Options
+
+### `-s/--skip <SKIP>`
+
+A list of test names to skip fuzzing.
+
+### `--subdir <SUBDIR>`
+
+The directory containing the parser. This is primarily useful in multi-language repositories.
+
+### `--edits <EDITS>`
+
+The maximum number of edits to perform. The default is 3.
+
+### `--iterations <ITERATIONS>`
+
+The number of iterations to run. The default is 10.
+
+### `-i/--include <INCLUDE>`
+
+Only run tests whose names match this regex.
+
+### `-e/--exclude <EXCLUDE>`
+
+Skip tests whose names match this regex.
+
+### `--log-graphs`
+
+Outputs logs of the graphs of the stack and parse trees during parsing, as well as the actual parsing and lexing message.
+The graphs are constructed with [graphviz dot][dot], and the output is written to `log.html`.
+
+### `-l/--log`
+
+Outputs parsing and lexing logs. This logs to stderr.
+
+### `-r/--rebuild`
+
+Force a rebuild of the parser before running the fuzzer.
+
+[dot]: https://graphviz.org/doc/info/lang.html

docs/src/cli/generate.md

@@ -0,0 +1,62 @@
+# `tree-sitter generate`
+
+The most important command you'll use is `tree-sitter generate`. This command reads the `grammar.js` file in your current
+working directory and creates a file called `src/parser.c`, which implements the parser. After making changes to your grammar,
+just run `tree-sitter generate` again.
+
+```bash
+tree-sitter generate [OPTIONS] [GRAMMAR_PATH] # Aliases: gen, g
+```
+
+The grammar path argument allows you to specify a path to a `grammar.js` JavaScript file, or `grammar.json` JSON file.
+In case your `grammar.js` file is in a non-standard path, you can specify it yourself. But, if you are using a parser
+where `grammar.json` was already generated, or it was hand-written, you can tell the CLI to generate the parser *based*
+on this JSON file. This avoids relying on a JavaScript file and avoids the dependency on a JavaScript runtime.
+
+If there is an ambiguity or *local ambiguity* in your grammar, Tree-sitter will detect it during parser generation, and
+it will exit with a `Unresolved conflict` error message. To learn more about conflicts and how to handle them, check out
+the section on [`Structuring Rules Well`](../creating-parsers/3-writing-the-grammar.md#structuring-rules-well)
+in the user guide.
+
+## Options
+
+### `-l/--log`
+
+Print the log of the parser generation process. This is really only useful if you know what you're doing, or are investigating
+a bug in the CLI itself. It logs info such as what tokens are included in the error recovery state,
+what keywords were extracted, what states were split and why, and the entry point state.
+
+### `--abi <VERSION>`
+
+The ABI to use for parser generation. The default is ABI 15, with ABI 14 being a supported target.
+
+### `-b/--build`
+
+Compile all defined languages in the current directory. The cli will automatically compile the parsers after generation,
+and place them in the cache dir.
+
+### `-0/--debug-build`
+
+Compile the parser with debug flags enabled. This is useful when debugging issues that require a debugger like `gdb` or `lldb`.
+
+### `--libdir <PATH>`
+
+The directory to place the compiled parser(s) in.
+On Unix systems, the default path is `$XDG_CACHE_HOME/tree-sitter` if `$XDG_CACHE_HOME` is set,
+otherwise `$HOME/.config/tree-sitter` is used. On Windows, the default path is `%LOCALAPPDATA%\tree-sitter` if available,
+otherwise `$HOME\AppData\Local\tree-sitter` is used.
+
+### `-o/--output`
+
+The directory to place the generated parser in. The default is `src/` in the current directory.
+
+### `--report-states-for-rule <RULE>`
+
+Print the overview of states from the given rule. This is useful for debugging and understanding the generated parser's
+item sets for all given states in a given rule. To solely view state count numbers for rules, pass in `-` for the rule argument.
+To view the overview of states for every rule, pass in `*` for the rule argument.
+
+### `--js-runtime <EXECUTABLE>`
+
+The path to the JavaScript runtime executable to use when generating the parser. The default is `node`.
+Note that you can also set this with `TREE_SITTER_JS_RUNTIME`.

docs/src/cli/highlight.md

@@ -0,0 +1,51 @@
+# `tree-sitter highlight`
+
+You can run syntax highlighting on an arbitrary file using `tree-sitter highlight`. This can either output colors directly
+to your terminal using ANSI escape codes, or produce HTML (if the `--html` flag is passed). For more information, see
+[the syntax highlighting page](../3-syntax-highlighting.md).
+
+```bash
+tree-sitter highlight [OPTIONS] [PATHS]... # Aliases: hi
+```
+
+## Options
+
+### `-H/--html`
+
+Output an HTML document with syntax highlighting.
+
+### `--css-classes`
+
+Output HTML with CSS classes instead of inline styles.
+
+### `--check`
+
+Check that the highlighting captures conform strictly to the standards.
+
+### `--captures-path <CAPTURES_PATH>`
+
+The path to a file with captures. These captures would be considered the "standard" captures to compare against.
+
+### `--query-paths <QUERY_PATHS>`
+
+The paths to query files to use for syntax highlighting. These should end in `highlights.scm`.
+
+### `--scope <SCOPE>`
+
+The language scope to use for syntax highlighting. This is useful when the language is ambiguous.
+
+### `-t/--time`
+
+Print the time taken to highlight the file.
+
+### `-q/--quiet`
+
+Suppress main output.
+
+### `--paths <PATHS_FILE>`
+
+The path to a file that contains paths to source files to highlight
+
+### `--config-path <CONFIG_PATH>`
+
+The path to an alternative configuration (`config.json`) file. See [the init-config command](./init-config.md) for more information.

docs/src/cli/index.md

@@ -0,0 +1,4 @@
+# CLI Overview
+
+Let's go over all of the functionality of the `tree-sitter` command line interface.
+Once you feel that you have enough of a grasp on the CLI, you can move onto the grammar authoring section to learn more about writing your own parser.

docs/src/cli/init-config.md

@@ -0,0 +1,146 @@
+# `tree-sitter init-config`
+
+This command initializes a configuration file for the Tree-sitter CLI.
+
+```bash
+tree-sitter init-config
+```
+
+These directories are created in the "default" location for your platform:
+
+* On Unix, `$XDG_CONFIG_HOME/tree-sitter` or `$HOME/.config/tree-sitter`
+* On Windows, `%APPDATA%\tree-sitter` or `$HOME\AppData\Roaming\tree-sitter`
+
+> Note that the CLI will work if there's no config file present, falling back on default values > for each configuration
+> option.
+
+When you run the `init-config` command, it will print out the location of the file that it creates so that you can easily
+find and modify it.
+
+The configuration file is a JSON file that contains the following fields:
+
+## `parser-directories`
+
+The [`tree-sitter highlight`](./highlight.md) command takes one or more file paths, and tries to automatically determine,
+which language should be used to highlight those files. To do this, it needs to know *where* to look for Tree-sitter grammars
+on your filesystem. You can control this using the `"parser-directories"` key in your configuration file:
+
+```json
+{
+  "parser-directories": [
+    "/Users/my-name/code",
+    "/Users/my-name/other-code"
+  ]
+}
+```
+
+Any folder within one of these *parser directories* whose name begins with `tree-sitter-` will be treated as a Tree-sitter
+grammar repository.
+
+## `theme`
+
+The [Tree-sitter highlighting system](../3-syntax-highlighting.md) works by annotating ranges of source code with logical
+"highlight names" like `function.method`, `type.builtin`, `keyword`, etc. To decide what *color* should be used for rendering
+each highlight, a *theme* is needed.
+
+In your config file, the `"theme"` value is an object whose keys are dot-separated highlight names like
+`function.builtin` or `keyword`, and whose values are JSON expressions that represent text styling parameters.
+
+### Highlight Names
+
+A theme can contain multiple keys that share a common subsequence. Examples:
+
+* `variable` and `variable.parameter`
+* `function`, `function.builtin`, and `function.method`
+
+For a given highlight produced, styling will be determined based on the **longest matching theme key**. For example, the
+highlight `function.builtin.static` would match the key `function.builtin` rather than `function`.
+
+### Styling Values
+
+Styling values can be any of the following:
+
+* Integers from 0 to 255, representing ANSI terminal color ids.
+* Strings like `"#e45649"` representing hexadecimal RGB colors.
+* Strings naming basic ANSI colors like `"red"`, `"black"`, `"purple"`, or `"cyan"`.
+* Objects with the following keys:
+  * `color` — An integer or string as described above.
+  * `underline` — A boolean indicating whether the text should be underlined.
+  * `italic` — A boolean indicating whether the text should be italicized.
+  * `bold` — A boolean indicating whether the text should be bold-face.
+
+An example theme can be seen below:
+
+```json
+{
+  "function": 26,
+  "operator": {
+    "bold": true,
+    "color": 239
+  },
+  "variable.builtin": {
+    "bold": true
+  },
+  "variable.parameter": {
+    "underline": true
+  },
+  "type.builtin": {
+    "color": 23,
+    "bold": true
+  },
+  "keyword": 56,
+  "type": 23,
+  "number": {
+    "bold": true,
+    "color": 94
+  },
+  "constant": 94,
+  "attribute": {
+    "color": 124,
+    "italic": true
+  },
+  "comment": {
+    "color": 245,
+    "italic": true
+  },
+  "constant.builtin": {
+    "color": 94,
+    "bold": true
+  },
+}
+```
+
+## `parse-theme`
+
+The [`tree-sitter parse`](./parse.md) command will output a pretty-printed CST when the `-c/--cst` option is used. You can
+control what colors are used for various parts of the tree in your configuration file. Note that omitting a field will cause
+the relevant text to be rendered with its default color.
+
+```json
+{
+  "parse-theme": {
+    // The color of node kinds
+    "node-kind": [20, 20, 20],
+    // The color of text associated with a node
+    "node-text": [255, 255, 255],
+    // The color of node fields
+    "field": [42, 42, 42],
+    // The color of the range information for unnamed nodes
+    "row-color": [255, 255, 255],
+    // The color of the range information for named nodes
+    "row-color-named": [255, 130, 0],
+    // The color of extra nodes
+    "extra": [255, 0, 255],
+    // The color of ERROR nodes
+    "error": [255, 0, 0],
+    // The color of MISSING nodes and their associated text
+    "missing": [153, 75, 0],
+    // The color of newline characters
+    "line-feed": [150, 150, 150],
+    // The color of backtick characters
+    "backtick": [0, 200, 0],
+    // The color of literals
+    "literal": [0, 0, 200],
+  }
+}
+```

docs/src/cli/init.md

@@ -0,0 +1,190 @@
+# `tree-sitter init`
+
+The `init` command is your starting point for creating a new grammar. When you run it, it sets up a repository with all
+the essential files and structure needed for grammar development. Since the command includes git-related files by default,
+we recommend using git for version control of your grammar.
+
+```bash
+tree-sitter init [OPTIONS] # Aliases: i
+```
+
+## Options
+
+### `--update`
+
+Update outdated generated files, if needed.
+
+## Structure of `tree-sitter.json`
+
+The main file of interest for users to configure is `tree-sitter.json`, which tells the CLI information about your grammar,
+such as the location of queries.
+
+### The `grammars` field
+
+This field is an array of objects, though you typically only need one object in this array unless your repo has
+multiple grammars (for example, `Typescript` and `TSX`).
+
+### Example
+
+Typically, the objects in the `"tree-sitter"` array only needs to specify a few keys:
+
+```json
+{
+  "tree-sitter": [
+    {
+      "scope": "source.ruby",
+      "file-types": [
+        "rb",
+        "gemspec",
+        "Gemfile",
+        "Rakefile"
+      ],
+      "first-line-regex": "#!.*\\bruby$"
+    }
+  ]
+}
+```
+
+#### Basic Fields
+
+These keys specify basic information about the parser:
+
+- `scope` (required) — A string like `"source.js"` that identifies the language.
+We strive to match the scope names used by popular [TextMate grammars][textmate] and by the [Linguist][linguist] library.
+
+- `path` — A relative path from the directory containing `tree-sitter.json` to another directory containing the `src/`
+folder, which contains the actual generated parser. The default value is `"."`
+(so that `src/` is in the same folder as `tree-sitter.json`), and this very rarely needs to be overridden.
+
+- `external-files` — A list of relative paths from the root dir of a
+parser to files that should be checked for modifications during recompilation.
+This is useful during development to have changes to other files besides scanner.c
+be picked up by the cli.
+
+#### Language Detection
+
+These keys help to decide whether the language applies to a given file:
+
+- `file-types` — An array of filename suffix strings. The grammar will be used for files whose names end with one of
+these suffixes. Note that the suffix may match an *entire* filename.
+
+- `first-line-regex` — A regex pattern that will be tested against the first line of a file
+to determine whether this language applies to the file. If present, this regex will be used for any file whose
+language does not match any grammar's `file-types`.
+
+- `content-regex` — A regex pattern that will be tested against the contents of the file
+to break ties in cases where multiple grammars matched the file using the above two criteria. If the regex matches,
+this grammar will be preferred over another grammar with no `content-regex`. If the regex does not match, a grammar with
+no `content-regex` will be preferred over this one.
+
+- `injection-regex` — A regex pattern that will be tested against a *language name* to determine whether this language
+should be used for a potential *language injection* site.
+Language injection is described in more detail in [the relevant section](../3-syntax-highlighting.md#language-injection).
+
+#### Query Paths
+
+These keys specify relative paths from the directory containing `tree-sitter.json` to the files that control syntax highlighting:
+
+- `highlights` — Path to a *highlight query*. Default: `queries/highlights.scm`
+- `locals` — Path to a *local variable query*. Default: `queries/locals.scm`.
+- `injections` — Path to an *injection query*. Default: `queries/injections.scm`.
+- `tags` — Path to an *tag query*. Default: `queries/tags.scm`.
+
+### The `metadata` field
+
+This field contains information that tree-sitter will use to populate relevant bindings' files, especially their versions.
+Typically, this will all be set up when you run `tree-sitter init`, but you are welcome to update it as you see fit.
+
+- `version` (required) — The current version of your grammar, which should follow [semver][semver]
+- `license` — The license of your grammar, which should be a valid [SPDX license][spdx]
+- `description` — The brief description of your grammar
+- `authors` (required) — An array of objects that contain a `name` field, and optionally an `email` and `url` field.
+Each field is a string
+- `links` — An object that contains a `repository` field, and optionally a `homepage` field. Each field is a string
+- `namespace` — The namespace for the `Java` and `Kotlin` bindings, defaults to `io.github.tree-sitter` if not provided
+
+### The `bindings` field
+
+This field controls what bindings are generated when the `init` command is run.
+Each key is a language name, and the value is a boolean.
+
+- `c` (default: `true`)
+- `go` (default: `true`)
+- `java` (default: `false`)
+- `kotlin` (default: `false`)
+- `node` (default: `true`)
+- `python` (default: `true`)
+- `rust` (default: `true`)
+- `swift` (default: `false`)
+
+## Binding Files
+
+When you run `tree-sitter init`, the CLI will also generate a number of files in your repository that allow for your parser
+to be used from different language. Here is a list of these bindings files that are generated, and what their purpose is:
+
+### C/C++
+
+- `Makefile` — This file tells [`make`][make] how to compile your language.
+- `CMakeLists.txt` — This file tells [`cmake`][cmake] how to compile your language.
+- `bindings/c/tree-sitter-language.h` — This file provides the C interface of your language.
+- `bindings/c/tree-sitter-language.pc` — This file provides [pkg-config][pkg-config] metadata about your language's C library.
+- `src/tree_sitter/parser.h` — This file provides some basic C definitions that are used in your generated `parser.c` file.
+- `src/tree_sitter/alloc.h` — This file provides some memory allocation macros that are to be used in your external scanner,
+if you have one.
+- `src/tree_sitter/array.h` — This file provides some array macros that are to be used in your external scanner,
+if you have one.
+
+### Go
+
+- `go.mod` — This file is the manifest of the Go module.
+- `bindings/go/binding.go` — This file wraps your language in a Go module.
+- `bindings/go/binding_test.go` — This file contains a test for the Go package.
+
+### Node
+
+- `binding.gyp` — This file tells Node.js how to compile your language.
+- `package.json` — This file is the manifest of the Node.js package.
+- `bindings/node/binding.cc` — This file wraps your language in a JavaScript module for Node.js.
+- `bindings/node/index.js` — This is the file that Node.js initially loads when using your language.
+- `bindings/node/index.d.ts` — This file provides type hints for your parser when used in TypeScript.
+- `bindings/node/binding_test.js` — This file contains a test for the Node.js package.
+
+### Python
+
+- `pyproject.toml` — This file is the manifest of the Python package.
+- `setup.py` — This file tells Python how to compile your language.
+- `bindings/python/tree_sitter_language/binding.c` — This file wraps your language in a Python module.
+- `bindings/python/tree_sitter_language/__init__.py` — This file tells Python how to load your language.
+ `bindings/python/tree_sitter_language/__init__.pyi` — This file provides type hints for your parser when used in Python.
+- `bindings/python/tree_sitter_language/py.typed` — This file provides type hints for your parser when used in Python.
+- `bindings/python/tests/test_binding.py` — This file contains a test for the Python package.
+
+### Rust
+
+- `Cargo.toml` — This file is the manifest of the Rust package.
+- `bindings/rust/lib.rs` — This file wraps your language in a Rust crate when used in Rust.
+- `bindings/rust/build.rs` — This file wraps the building process for the Rust crate.
+
+### Swift
+
+- `Package.swift` — This file tells Swift how to compile your language.
+- `bindings/swift/TreeSitterLanguage/language.h` — This file wraps your language in a Swift module when used in Swift.
+- `bindings/swift/TreeSitterLanguageTests/TreeSitterLanguageTests.swift` — This file contains a test for the Swift package.
+
+### Additional Files
+
+Additionally, there's a few other files that are generated when you run `tree-sitter init`,
+that aim to improve the development experience:
+
+- `.editorconfig` — This file tells your editor how to format your code. More information about this file can be found [here][editorconfig]
+- `.gitattributes` — This file tells Git how to handle line endings, and tells GitHub what files are generated.
+- `.gitignore` — This file tells Git what files to ignore when committing changes.
+
+[cmake]: https://cmake.org/cmake/help/latest
+[editorconfig]: https://editorconfig.org
+[linguist]: https://github.com/github/linguist
+[make]: https://www.gnu.org/software/make/manual/make.html
+[pkg-config]: https://www.freedesktop.org/wiki/Software/pkg-config
+[semver]: https://semver.org
+[spdx]: https://spdx.org/licenses
+[textmate]: https://macromates.com/manual/en/language_grammars

docs/src/cli/parse.md

@@ -0,0 +1,97 @@
+# `tree-sitter parse`
+
+The `parse` command parses source files using a Tree-sitter parser. You can pass any number of file paths and glob patterns
+to `tree-sitter parse`, and it will parse all the given files. The command will exit with a non-zero status code if any
+parse errors occurred.
+
+```bash
+tree-sitter parse [OPTIONS] [PATHS]... # Aliases: p
+```
+
+## Options
+
+### `--paths <PATHS_FILE>`
+
+The path to a file that contains paths to source files to parse.
+
+### `--scope <SCOPE>`
+
+The language scope to use for parsing. This is useful when the language is ambiguous.
+
+### `-d/--debug`
+
+Outputs parsing and lexing logs. This logs to stderr.
+
+### `-0/--debug-build`
+
+Compile the parser with debug flags enabled. This is useful when debugging issues that require a debugger like `gdb` or `lldb`.
+
+### `-D/--debug-graph`
+
+Outputs logs of the graphs of the stack and parse trees during parsing, as well as the actual parsing and lexing message.
+The graphs are constructed with [graphviz dot][dot], and the output is written to `log.html`.
+
+### `--wasm`
+
+Compile and run the parser as a WASM module.
+
+### `--dot`
+
+Output the parse tree with [graphviz dot][dot].
+
+### `-x/--xml`
+
+Output the parse tree in XML format.
+
+### `-c/--cst`
+
+Output the parse tree in a pretty-printed CST format.
+
+### `-s/--stat`
+
+Show parsing statistics.
+
+### `--timeout <TIMEOUT>`
+
+Set the timeout for parsing a single file, in microseconds.
+
+### `-t/--time`
+
+Print the time taken to parse the file. If edits are provided, this will also print the time taken to parse the file after
+each edit.
+
+### `-q/--quiet`
+
+Suppress main output.
+
+### `--edits <EDITS>...`
+
+Apply edits after parsing the file. Edits are in the form of `row, col delcount insert_text` where row and col are 0-indexed.
+
+### `--encoding <ENCODING>`
+
+Set the encoding of the input file. By default, the CLI will look for the [`BOM`][bom] to determine if the file is encoded
+in `UTF-16BE` or `UTF-16LE`. If no `BOM` is present, `UTF-8` is the default. One of `utf8`, `utf16-le`, `utf16-be`.
+
+### `--open-log`
+
+When using the `--debug-graph` option, open the log file in the default browser.
+
+### `--config-path <CONFIG_PATH>`
+
+The path to an alternative configuration (`config.json`) file. See [the init-config command](./init-config.md) for more information.
+
+### `-n/--test-number <TEST_NUMBER>`
+
+Parse a specific test in the corpus. The test number is the same number that appears in the output of `tree-sitter test`.
+
+### `-r/--rebuild`
+
+Force a rebuild of the parser before running tests.
+
+### `--no-ranges`
+
+Omit the node's ranges from the default parse output. This is useful when copying S-Expressions to a test file.
+
+[dot]: https://graphviz.org/doc/info/lang.html
+[bom]: https://en.wikipedia.org/wiki/Byte_order_mark

docs/src/cli/playground.md

@@ -0,0 +1,20 @@
+# `tree-sitter playground`
+
+The `playground` command allows you to start a local playground to test your parser interactively.
+
+```bash
+tree-sitter playground [OPTIONS] # Aliases: play, pg, web-ui
+```
+
+Note that you must have already built the parser as a WASM module. This can be done with the [`build`](./build.md) subcommand
+(`tree-sitter build --wasm`).
+
+## Options
+
+### `-q/--quiet`
+
+Don't automatically open the playground in the default browser.
+
+### `--grammar-path <GRAMMAR_PATH>`
+
+The path to the directory containing the grammar and wasm files.

docs/src/cli/query.md

@@ -0,0 +1,45 @@
+# `tree-sitter query`
+
+The `query` command is used to run a query on a parser, and view the results.
+
+```bash
+tree-sitter query [OPTIONS] <QUERY_PATH> [PATHS]... # Aliases: q
+```
+
+## Options
+
+### `-t/--time`
+
+Print the time taken to execute the query on the file.
+
+### `-q/--quiet`
+
+Suppress main output.
+
+### `--paths <PATHS_FILE>`
+
+The path to a file that contains paths to source files in which the query will be executed.
+
+### `--byte-range <BYTE_RANGE>`
+
+The range of byte offsets in which the query will be executed. The format is `start_byte:end_byte`.
+
+### `--row-range <ROW_RANGE>`
+
+The range of rows in which the query will be executed. The format is `start_row:end_row`.
+
+### `--scope <SCOPE>`
+
+The language scope to use for parsing and querying. This is useful when the language is ambiguous.
+
+### `-c/--captures`
+
+Order the query results by captures instead of matches.
+
+### `--test`
+
+Whether to run query tests or not.
+
+### `--config-path <CONFIG_PATH>`
+
+The path to an alternative configuration (`config.json`) file. See [the init-config command](./init-config.md) for more information.

docs/src/cli/tags.md

@@ -0,0 +1,30 @@
+# `tree-sitter tags`
+
+You can run symbol tagging on an arbitrary file using `tree-sitter tags`. This will output a list of tags.
+For more information, see [the code navigation page](../4-code-navigation.md#tagging-and-captures).
+
+```bash
+tree-sitter tags [OPTIONS] [PATHS]...
+```
+
+## Options
+
+### `--scope <SCOPE>`
+
+The language scope to use for symbol tagging. This is useful when the language is ambiguous.
+
+### `-t/--time`
+
+Print the time taken to generate tags for the file.
+
+### `-q/--quiet`
+
+Suppress main output.
+
+### `--paths <PATHS_FILE>`
+
+The path to a file that contains paths to source files to tag.
+
+### `--config-path <CONFIG_PATH>`
+
+The path to an alternative configuration (`config.json`) file. See [the init-config command](./init-config.md) for more information.

docs/src/cli/test.md

@@ -0,0 +1,68 @@
+# `tree-sitter test`
+
+The `test` command is used to run the test suite for a parser.
+
+```bash
+tree-sitter test [OPTIONS] # Aliases: t
+```
+
+## Options
+
+### `-i/--include <INCLUDE>`
+
+Only run tests whose names match this regex.
+
+### `-e/--exclude <EXCLUDE>`
+
+Skip tests whose names match this regex.
+
+### `-u/--update`
+
+Update the expected output of tests. Note that tests containing `ERROR` nodes or `MISSING` nodes will not be updated.
+
+### `-d/--debug`
+
+Outputs parsing and lexing logs. This logs to stderr.
+
+### `-0/--debug-build`
+
+Compile the parser with debug flags enabled. This is useful when debugging issues that require a debugger like `gdb` or `lldb`.
+
+### `-D/--debug-graph`
+
+Outputs logs of the graphs of the stack and parse trees during parsing, as well as the actual parsing and lexing message.
+The graphs are constructed with [graphviz dot][dot], and the output is written to `log.html`.
+
+### `--wasm`
+
+Compile and run the parser as a WASM module.
+
+### `--open-log`
+
+When using the `--debug-graph` option, open the log file in the default browser.
+
+### `--config-path <CONFIG_PATH>`
+
+The path to an alternative configuration (`config.json`) file. See [the init-config command](./init-config.md) for more information.
+
+### `--show-fields`
+
+Force showing fields in test diffs.
+
+### `--stat <STAT>`
+
+Show parsing statistics when tests are being run. One of `all`, `outliers-and-total`, or `total-only`.
+
+- `all`: Show statistics for every test.
+
+- `outliers-and-total`: Show statistics only for outliers, and total statistics.
+
+- `total-only`: Show only total statistics.
+
+### `-r/--rebuild`
+
+Force a rebuild of the parser before running tests.
+
+### `--overview-only`
+
+Only show the overview of the test results, and not the diff.

docs/src/cli/version.md

@@ -0,0 +1,24 @@
+# `tree-sitter version`
+
+The `version` command upgrades the version of your grammar.
+
+```bash
+tree-sitter version <VERSION> # Aliases: publish
+```
+
+This will update the version in several files, if they exist:
+
+* tree-sitter.json
+* Cargo.toml
+* Cargo.lock
+* package.json
+* package-lock.json
+* Makefile
+* CMakeLists.txt
+* pyproject.toml
+
+As a grammar author, you should keep the version of your grammar in sync across
+different bindings. However, doing so manually is error-prone and tedious, so
+this command takes care of the burden. If you are using a version control system,
+it is recommended to commit the changes made by this command, and to tag the
+commit with the new version.