docs: update badges; fix markdown lint complains

Linter config `.vscode/settings.json`:
```json
{
    "[markdown]": {
        "files.trimTrailingWhitespace": false,
    },
    "markdownlint.config": {
        "default": true,
        // "ul-style": {
        //     "style": "asterisk"
        // },
        "MD001": false,
        "MD024": false,
        "MD025": false,
        "MD033": false,
        "MD041": false,
        "MD053": false,
    },
}
```

Author: ahlinc

README.md

@@ -1,8 +1,11 @@
 # tree-sitter
 
-[![CICD](https://github.com/tree-sitter/tree-sitter/actions/workflows/CICD.yml/badge.svg)](https://github.com/tree-sitter/tree-sitter/actions/workflows/CICD.yml)
+[![CICD badge]][CICD]
 [![DOI](https://zenodo.org/badge/14164618.svg)](https://zenodo.org/badge/latestdoi/14164618)
 
+[CICD badge]: https://github.com/tree-sitter/tree-sitter/actions/workflows/CICD.yml/badge.svg
+[CICD]: https://github.com/tree-sitter/tree-sitter/actions/workflows/CICD.yml
+
 Tree-sitter is a parser generator tool and an incremental parsing library. It can build a concrete syntax tree for a source file and efficiently update the syntax tree as the source file is edited. Tree-sitter aims to be:
 
 - **General** enough to parse any programming language

cli/README.md

@@ -1,7 +1,11 @@
-Tree-sitter CLI
-===============
+# Tree-sitter CLI
 
-[![Crates.io](https://img.shields.io/crates/v/tree-sitter-cli.svg)](https://crates.io/crates/tree-sitter-cli)
+[![crates.io badge]][crates.io] [![npmjs.com badge]][npmjs.com]
+
+[crates.io]: https://crates.io/crates/tree-sitter-cli
+[crates.io badge]: https://img.shields.io/crates/v/tree-sitter-cli.svg?color=%23B48723
+[npmjs.com]: https://www.npmjs.org/package/tree-sitter-cli
+[npmjs.com badge]: https://img.shields.io/npm/v/tree-sitter-cli.svg?color=%23BF4A4A
 
 The Tree-sitter CLI allows you to develop, test, and use Tree-sitter grammars from the command line. It works on MacOS, Linux, and Windows.
 
@@ -19,7 +23,7 @@ or with `npm`:
 npm install tree-sitter-cli
 ```
 
-You can also download a pre-built binary for your platform from [the releases page](https://github.com/tree-sitter/tree-sitter/releases/latest).
+You can also download a pre-built binary for your platform from [the releases page].
 
 ### Dependencies
 
@@ -30,8 +34,11 @@ The `tree-sitter` binary itself has no dependencies, but specific commands have
 
 ### Commands
 
-* `generate` - The `tree-sitter generate` command will generate a Tree-sitter parser based on the grammar in the current working directory. See [the documentation](https://tree-sitter.github.io/tree-sitter/creating-parsers) for more information.
+* `generate` - The `tree-sitter generate` command will generate a Tree-sitter parser based on the grammar in the current working directory. See [the documentation] for more information.
 
-* `test` - The `tree-sitter test` command will run the unit tests for the Tree-sitter parser in the current working directory. See [the documentation](https://tree-sitter.github.io/tree-sitter/creating-parsers) for more information.
+* `test` - The `tree-sitter test` command will run the unit tests for the Tree-sitter parser in the current working directory. See [the documentation] for more information.
 
 * `parse` - The `tree-sitter parse` command will parse a file (or list of files) using Tree-sitter parsers.
+
+[the documentation]: https://tree-sitter.github.io/tree-sitter/creating-parsers
+[the releases page]: https://github.com/tree-sitter/tree-sitter/releases/latest

docs/index.md

@@ -160,9 +160,9 @@ By convention, parsers are named with the language last, eg. tree-sitter-ruby.
 
 The design of Tree-sitter was greatly influenced by the following research papers:
 
-- [Practical Algorithms for Incremental Software Development Environments](https://www2.eecs.berkeley.edu/Pubs/TechRpts/1997/CSD-97-946.pdf)
-- [Context Aware Scanning for Parsing Extensible Languages](https://www-users.cse.umn.edu/~evw/pubs/vanwyk07gpce/vanwyk07gpce.pdf)
-- [Efficient and Flexible Incremental Parsing](https://harmonia.cs.berkeley.edu/papers/twagner-parsing.pdf)
-- [Incremental Analysis of Real Programming Languages](https://harmonia.cs.berkeley.edu/papers/twagner-glr.pdf)
-- [Error Detection and Recovery in LR Parsers](https://what-when-how.com/compiler-writing/bottom-up-parsing-compiler-writing-part-13)
-- [Error Recovery for LR Parsers](https://apps.dtic.mil/sti/pdfs/ADA043470.pdf)
+* [Practical Algorithms for Incremental Software Development Environments](https://www2.eecs.berkeley.edu/Pubs/TechRpts/1997/CSD-97-946.pdf)
+* [Context Aware Scanning for Parsing Extensible Languages](https://www-users.cse.umn.edu/~evw/pubs/vanwyk07gpce/vanwyk07gpce.pdf)
+* [Efficient and Flexible Incremental Parsing](https://harmonia.cs.berkeley.edu/papers/twagner-parsing.pdf)
+* [Incremental Analysis of Real Programming Languages](https://harmonia.cs.berkeley.edu/papers/twagner-glr.pdf)
+* [Error Detection and Recovery in LR Parsers](https://what-when-how.com/compiler-writing/bottom-up-parsing-compiler-writing-part-13)
+* [Error Recovery for LR Parsers](https://apps.dtic.mil/sti/pdfs/ADA043470.pdf)

docs/section-2-using-parsers.md

@@ -21,21 +21,21 @@ Alternatively, you can incorporate the library in a larger project's build syste
 
 **source file:**
 
-- `tree-sitter/lib/src/lib.c`
+* `tree-sitter/lib/src/lib.c`
 
 **include directories:**
 
-- `tree-sitter/lib/src`
-- `tree-sitter/lib/include`
+* `tree-sitter/lib/src`
+* `tree-sitter/lib/include`
 
 ### The Basic Objects
 
 There are four main types of objects involved when using Tree-sitter: languages, parsers, syntax trees, and syntax nodes. In C, these are called `TSLanguage`, `TSParser`, `TSTree`, and `TSNode`.
 
-- A `TSLanguage` is an opaque object that defines how to parse a particular programming language. The code for each `TSLanguage` is generated by Tree-sitter. Many languages are already available in separate git repositories within the [Tree-sitter GitHub organization](https://github.com/tree-sitter). See [the next page](./creating-parsers) for how to create new languages.
-- A `TSParser` is a stateful object that can be assigned a `TSLanguage` and used to produce a `TSTree` based on some source code.
-- A `TSTree` represents the syntax tree of an entire source code file. It contains `TSNode` instances that indicate the structure of the source code. It can also be edited and used to produce a new `TSTree` in the event that the source code changes.
-- A `TSNode` represents a single node in the syntax tree. It tracks its start and end positions in the source code, as well as its relation to other nodes like its parent, siblings and children.
+* A `TSLanguage` is an opaque object that defines how to parse a particular programming language. The code for each `TSLanguage` is generated by Tree-sitter. Many languages are already available in separate git repositories within the [Tree-sitter GitHub organization](https://github.com/tree-sitter). See [the next page](./creating-parsers) for how to create new languages.
+* A `TSParser` is a stateful object that can be assigned a `TSLanguage` and used to produce a `TSTree` based on some source code.
+* A `TSTree` represents the syntax tree of an entire source code file. It contains `TSNode` instances that indicate the structure of the source code. It can also be edited and used to produce a new `TSTree` in the event that the source code changes.
+* A `TSNode` represents a single node in the syntax tree. It tracks its start and end positions in the source code, as well as its relation to other nodes like its parent, siblings and children.
 
 ### An Example Program
 
@@ -442,31 +442,31 @@ Many code analysis tasks involve searching for patterns in syntax trees. Tree-si
 
 A _query_ consists of one or more _patterns_, where each pattern is an [S-expression](https://en.wikipedia.org/wiki/S-expression) that matches a certain set of nodes in a syntax tree. The expression to match a given node consists of a pair of parentheses containing two things: the node's type, and optionally, a series of other S-expressions that match the node's children. For example, this pattern would match any `binary_expression` node whose children are both `number_literal` nodes:
 
-``` scheme
+```scheme
 (binary_expression (number_literal) (number_literal))
 ```
 
 Children can also be omitted. For example, this would match any `binary_expression` where at least _one_ of child is a `string_literal` node:
 
-``` scheme
+```scheme
 (binary_expression (string_literal))
 ```
 
 #### Fields
 
 In general, it's a good idea to make patterns more specific by specifying [field names](#node-field-names) associated with child nodes. You do this by prefixing a child pattern with a field name followed by a colon. For example, this pattern would match an `assignment_expression` node where the `left` child is a `member_expression` whose `object` is a `call_expression`.
 
-``` scheme
+```scheme
 (assignment_expression
   left: (member_expression
     object: (call_expression)))
 ```
 
 #### Negated Fields
 
-You can also constrain a pattern so that it only matches nodes that *lack* a certain field. To do this, add a field name prefixed by a `!` within the parent pattern. For example, this pattern would match a class declaration with no type parameters:
+You can also constrain a pattern so that it only matches nodes that _lack_ a certain field. To do this, add a field name prefixed by a `!` within the parent pattern. For example, this pattern would match a class declaration with no type parameters:
 
-``` scheme
+```scheme
 (class_declaration
   name: (identifier) @class_name
   !type_parameters)
@@ -476,7 +476,7 @@ You can also constrain a pattern so that it only matches nodes that *lack* a cer
 
 The parenthesized syntax for writing nodes only applies to [named nodes](#named-vs-anonymous-nodes). To match specific anonymous nodes, you write their name between double quotes. For example, this pattern would match any `binary_expression` where the operator is `!=` and the right side is `null`:
 
-``` scheme
+```scheme
 (binary_expression
   operator: "!="
   right: (null))
@@ -488,15 +488,15 @@ When matching patterns, you may want to process specific nodes within the patter
 
 For example, this pattern would match any assignment of a `function` to an `identifier`, and it would associate the name `the-function-name` with the identifier:
 
-``` scheme
+```scheme
 (assignment_expression
   left: (identifier) @the-function-name
   right: (function))
 ```
 
 And this pattern would match all method definitions, associating the name `the-method-name` with the method name, `the-class-name` with the containing class name:
 
-``` scheme
+```scheme
 (class_declaration
   name: (identifier) @the-class-name
   body: (class_body
@@ -510,21 +510,21 @@ You can match a repeating sequence of sibling nodes using the postfix `+` and `*
 
 For example, this pattern would match a sequence of one or more comments:
 
-``` scheme
+```scheme
 (comment)+
 ```
 
 This pattern would match a class declaration, capturing all of the decorators if any were present:
 
-``` scheme
+```scheme
 (class_declaration
   (decorator)* @the-decorator
   name: (identifier) @the-name)
 ```
 
 You can also mark a node as optional using the `?` operator. For example, this pattern would match all function calls, capturing a string argument if one was present:
 
-``` scheme
+```scheme
 (call_expression
   function: (identifier) @the-function
   arguments: (arguments (string)? @the-string-arg))
@@ -534,7 +534,7 @@ You can also mark a node as optional using the `?` operator. For example, this p
 
 You can also use parentheses for grouping a sequence of _sibling_ nodes. For example, this pattern would match a comment followed by a function declaration:
 
-``` scheme
+```scheme
 (
   (comment)
   (function_declaration)
@@ -543,7 +543,7 @@ You can also use parentheses for grouping a sequence of _sibling_ nodes. For exa
 
 Any of the quantification operators mentioned above (`+`, `*`, and `?`) can also be applied to groups. For example, this pattern would match a comma-separated series of numbers:
 
-``` scheme
+```scheme
 (
   (number)
   ("," (number))*
@@ -558,7 +558,7 @@ This is similar to _character classes_ from regular expressions (`[abc]` matches
 For example, this pattern would match a call to either a variable or an object property.
 In the case of a variable, capture it as `@function`, and in the case of a property, capture it as `@method`:
 
-``` scheme
+```scheme
 (call_expression
   function: [
     (identifier) @function
@@ -569,7 +569,7 @@ In the case of a variable, capture it as `@function`, and in the case of a prope
 
 This pattern would match a set of possible keyword tokens, capturing them as `@keyword`:
 
-``` scheme
+```scheme
 [
   "break"
   "delete"
@@ -592,7 +592,7 @@ and `_` will match any named or anonymous node.
 
 For example, this pattern would match any node inside a call:
 
-``` scheme
+```scheme
 (call (_) @call.inner)
 ```
 
@@ -602,21 +602,21 @@ The anchor operator, `.`, is used to constrain the ways in which child patterns
 
 When `.` is placed before the _first_ child within a parent pattern, the child will only match when it is the first named node in the parent. For example, the below pattern matches a given `array` node at most once, assigning the `@the-element` capture to the first `identifier` node in the parent `array`:
 
-``` scheme
+```scheme
 (array . (identifier) @the-element)
 ```
 
 Without this anchor, the pattern would match once for every identifier in the array, with `@the-element` bound to each matched identifier.
 
 Similarly, an anchor placed after a pattern's _last_ child will cause that child pattern to only match nodes that are the last named child of their parent. The below pattern matches only nodes that are the last named child within a `block`.
 
-``` scheme
+```scheme
 (block (_) @last-expression .)
 ```
 
 Finally, an anchor _between_ two child patterns will cause the patterns to only match nodes that are immediate siblings. The pattern below, given a long dotted name like `a.b.c.d`, will only match pairs of consecutive identifiers: `a, b`, `b, c`, and `c, d`.
 
-``` scheme
+```scheme
 (dotted_name
   (identifier) @prev-id
   .
@@ -633,7 +633,7 @@ You can also specify arbitrary metadata and conditions associated with a pattern
 
 For example, this pattern would match identifier whose names is written in `SCREAMING_SNAKE_CASE`:
 
-``` scheme
+```scheme
 (
   (identifier) @constant
   (#match? @constant "^[A-Z][A-Z_]+")
@@ -642,7 +642,7 @@ For example, this pattern would match identifier whose names is written in `SCRE
 
 And this pattern would match key-value pairs where the `value` is an identifier with the same name as the key:
 
-``` scheme
+```scheme
 (
   (pair
     key: (property_identifier) @key-name
@@ -723,8 +723,8 @@ The node types file contains an array of objects, each of which describes a part
 
 Every object in this array has these two entries:
 
-- `"type"` - A string that indicates which grammar rule the node represents. This corresponds to the `ts_node_type` function described [above](#syntax-nodes).
-- `"named"` - A boolean that indicates whether this kind of node corresponds to a rule name in the grammar or just a string literal. See [above](#named-vs-anonymous-nodes) for more info.
+* `"type"` - A string that indicates which grammar rule the node represents. This corresponds to the `ts_node_type` function described [above](#syntax-nodes).
+* `"named"` - A boolean that indicates whether this kind of node corresponds to a rule name in the grammar or just a string literal. See [above](#named-vs-anonymous-nodes) for more info.
 
 Examples:
 
@@ -745,14 +745,14 @@ Together, these two fields constitute a unique identifier for a node type; no tw
 
 Many syntax nodes can have _children_. The node type object describes the possible children that a node can have using the following entries:
 
-- `"fields"` - An object that describes the possible [fields](#node-field-names) that the node can have. The keys of this object are field names, and the values are _child type_ objects, described below.
-- `"children"` - Another _child type_ object that describes all of the node's possible _named_ children _without_ fields.
+* `"fields"` - An object that describes the possible [fields](#node-field-names) that the node can have. The keys of this object are field names, and the values are _child type_ objects, described below.
+* `"children"` - Another _child type_ object that describes all of the node's possible _named_ children _without_ fields.
 
 A _child type_ object describes a set of child nodes using the following entries:
 
-- `"required"` - A boolean indicating whether there is always _at least one_ node in this set.
-- `"multiple"` - A boolean indicating whether there can be _multiple_ nodes in this set.
-- `"types"`- An array of objects that represent the possible types of nodes in this set. Each object has two keys: `"type"` and `"named"`, whose meanings are described above.
+* `"required"` - A boolean indicating whether there is always _at least one_ node in this set.
+* `"multiple"` - A boolean indicating whether there can be _multiple_ nodes in this set.
+* `"types"`- An array of objects that represent the possible types of nodes in this set. Each object has two keys: `"type"` and `"named"`, whose meanings are described above.
 
 Example with fields:
 
@@ -812,7 +812,7 @@ In Tree-sitter grammars, there are usually certain rules that represent abstract
 
 Normally, hidden rules are not mentioned in the node types file, since they don't appear in the syntax tree. But if you add a hidden rule to the grammar's [`supertypes` list](./creating-parsers#the-grammar-dsl), then it _will_ show up in the node types file, with the following special entry:
 
-- `"subtypes"` - An array of objects that specify the _types_ of nodes that this 'supertype' node can wrap.
+* `"subtypes"` - An array of objects that specify the _types_ of nodes that this 'supertype' node can wrap.
 
 Example: