From ea9ddbe1901af733ddf9a35cf9aa175b8ce1bdf4 Mon Sep 17 00:00:00 2001 From: Amaan Qureshi Date: Sun, 30 Aug 2026 15:42:41 -0400 Subject: [PATCH] docs: replace mdbook-admonish with mdBook admonitions --- .github/workflows/docs.yml | 8 +- docs/book.toml | 10 +- docs/package.nix | 6 +- docs/src/3-syntax-highlighting.md | 36 +- docs/src/6-contributing.md | 26 +- docs/src/7-playground.md | 5 +- docs/src/assets/css/mdbook-admonish.css | 348 ------------------ docs/src/cli/init-config.md | 10 +- docs/src/cli/playground.md | 7 +- docs/src/cli/test.md | 5 +- .../src/creating-parsers/1-getting-started.md | 17 +- .../src/creating-parsers/2-the-grammar-dsl.md | 27 +- .../creating-parsers/3-writing-the-grammar.md | 54 ++- .../creating-parsers/4-external-scanners.md | 22 +- docs/src/creating-parsers/5-writing-tests.md | 21 +- docs/src/using-parsers/2-basic-parsing.md | 10 +- docs/src/using-parsers/3-advanced-parsing.md | 5 +- docs/src/using-parsers/4-walking-trees.md | 13 +- .../queries/3-predicates-and-directives.md | 17 +- docs/src/using-parsers/queries/4-api.md | 7 +- 20 files changed, 130 insertions(+), 524 deletions(-) delete mode 100644 docs/src/assets/css/mdbook-admonish.css diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 7d2d5a243..5cec1f54a 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -18,22 +18,16 @@ jobs: - name: Checkout repository uses: actions/checkout@v7.0.1 - - name: Set up Rust - uses: actions-rust-lang/setup-rust-toolchain@v1 - - name: Install mdbook env: GH_TOKEN: ${{ github.token }} run: | jq_expr='.assets[] | select(.name | contains("x86_64-unknown-linux-gnu")) | .browser_download_url' - url=$(gh api repos/rust-lang/mdbook/releases/tags/v0.4.52 --jq "$jq_expr") + url=$(gh api repos/rust-lang/mdbook/releases/tags/v0.5.4 --jq "$jq_expr") mkdir mdbook curl -sSL "$url" | tar -xz -C mdbook printf '%s/mdbook\n' "$PWD" >> "$GITHUB_PATH" - - name: Install mdbook-admonish - run: cargo install mdbook-admonish - - name: Build Book run: mdbook build docs diff --git a/docs/book.toml b/docs/book.toml index 8efc620e8..ce9c45fa9 100644 --- a/docs/book.toml +++ b/docs/book.toml @@ -5,10 +5,10 @@ src = "src" title = "Tree-sitter" [output.html] -additional-css = [ "src/assets/css/playground.css", "src/assets/css/mdbook-admonish.css" ] +additional-css = [ "src/assets/css/playground.css" ] additional-js = [ "src/assets/js/playground.js" ] edit-url-template = "https://github.com/tree-sitter/tree-sitter/edit/master/docs/{path}" -git-repository-icon = "fa-github" +git-repository-icon = "fab-github" git-repository-url = "https://github.com/tree-sitter/tree-sitter" [output.html.search] @@ -18,9 +18,3 @@ boost-title = 2 expand = true limit-results = 20 use-boolean-and = true - -[preprocessor] - -[preprocessor.admonish] -assets_version = "3.0.2" # do not edit: managed by `mdbook-admonish install` -command = "mdbook-admonish" diff --git a/docs/package.nix b/docs/package.nix index 1d07631f8..8e5bbccf8 100644 --- a/docs/package.nix +++ b/docs/package.nix @@ -3,7 +3,6 @@ lib, version, mdbook, - mdbook-admonish, }: stdenv.mkDerivation { inherit version; @@ -11,10 +10,7 @@ stdenv.mkDerivation { src = ./.; pname = "tree-sitter-docs"; - nativeBuildInputs = [ - mdbook - mdbook-admonish - ]; + nativeBuildInputs = [ mdbook ]; buildPhase = '' mdbook build diff --git a/docs/src/3-syntax-highlighting.md b/docs/src/3-syntax-highlighting.md index 6648cb00f..d0357635e 100644 --- a/docs/src/3-syntax-highlighting.md +++ b/docs/src/3-syntax-highlighting.md @@ -154,13 +154,14 @@ Then, in our config file, we could map each of these highlight names to a color: Running `tree-sitter highlight` on this Go file would produce output like this: -```admonish example collapsible=true, title='Output' +
+Output 
 func increment(a int) int {
     return a + 1
 }
-``` +
### Local Variables @@ -297,7 +298,8 @@ and blocks create local *scopes*, parameters and assignments create *definitions Running `tree-sitter highlight` on this ruby file would produce output like this: -```admonish example collapsible=true, title='Output' +
+Output 
 def process_list(list)
   context = current_context
@@ -305,11 +307,11 @@ Running `tree-sitter highlight` on this ruby file would produce output like this
     process_item(item, context)
   end
 end
-
+
 item = 5
 list = [item]
-``` +
### Language Injection @@ -417,19 +419,19 @@ var abc = function(d) { }; ``` -```admonish cite title='From the Sublime text docs' -The two types of tests are: +> **From the Sublime Text docs** +> +> The two types of tests are: +> +> **Caret**: ^ this will test the following selector against the scope on the most recent non-test line. It will test it +> at the same column the ^ is in. Consecutive ^s will test each column against the selector. +> +> **Arrow**: <- this will test the following selector against the scope on the most recent non-test line. It will test it +> at the same column as the comment character is in. -**Caret**: ^ this will test the following selector against the scope on the most recent non-test line. It will test it -at the same column the ^ is in. Consecutive ^s will test each column against the selector. - -**Arrow**: <- this will test the following selector against the scope on the most recent non-test line. It will test it -at the same column as the comment character is in. -``` -```admonish note -An exclamation mark (`!`) can be used to negate a selector. For example, `!keyword` will match any scope that is -not the `keyword` class. -``` +> [!NOTE] +> An exclamation mark (`!`) can be used to negate a selector. For example, `!keyword` will match any scope that is +> not the `keyword` class. [erb]: https://en.wikipedia.org/wiki/ERuby [highlight crate]: https://github.com/tree-sitter/tree-sitter/tree/master/crates/highlight diff --git a/docs/src/6-contributing.md b/docs/src/6-contributing.md index ca53fd566..42dfca9e8 100644 --- a/docs/src/6-contributing.md +++ b/docs/src/6-contributing.md @@ -89,9 +89,8 @@ npm install # or your JS package manager of choice npm run build ``` -```admonish note -If using a local Emscripten installation, the version must match the one [pinned by this repository][emscripten-version]. -``` +> [!NOTE] +> If using a local Emscripten installation, the version must match the one [pinned by this repository][emscripten-version]. Build the Rust libraries and the CLI: @@ -301,9 +300,8 @@ edit and hit the edit icon at the top right of the page. ### Prerequisites for Local Development -```admonish note -We're assuming you have `cargo` installed, the Rust package manager. -``` +> [!NOTE] +> We're assuming you have `cargo` installed, the Rust package manager. To run and iterate on the docs locally, the [`mdbook`][mdbook cli] CLI tool is required, which can be installed with @@ -313,16 +311,14 @@ cargo install mdbook ``` You might have noticed we have some fancy admonitions sprinkled throughout the documentation, like the note above. -These are created using [`mdbook-admonish`][admonish], a [preprocessor][preprocessor] for `mdBook`. As such, this is also -a requirement for developing the documentation locally. To install it, run: +These are built into `mdBook`, and are written as a blockquote whose first line names the kind, one of `NOTE`, `TIP`, +`IMPORTANT`, `WARNING`, or `CAUTION`. See the [reference][admonitions] for more information. -```sh -cargo install mdbook-admonish +```md +> [!NOTE] +> Something worth pointing out. ``` -Once you've installed it, you can begin using admonitions in your markdown files. See the [reference][admonish reference] -for more information. - ### Spinning it up Now that you've installed the prerequisites, you can run the following command to start a local server: @@ -343,8 +339,7 @@ at [`docs/src/assets/css/playground.css`][playground css]. The editor of choice and the tree-sitter module is fetched from [here][js url]. This, along with the Wasm module and Wasm parsers, live in the [.github.io repo][gh.io repo]. -[admonish]: https://github.com/tommilligan/mdbook-admonish -[admonish reference]: https://tommilligan.github.io/mdbook-admonish/reference.html +[admonitions]: https://rust-lang.github.io/mdBook/format/markdown.html#admonitions [binaryen]: https://github.com/WebAssembly/binaryen [binaryen-releases]: https://github.com/WebAssembly/binaryen/releases [config crate]: https://crates.io/crates/tree-sitter-config @@ -375,7 +370,6 @@ and the tree-sitter module is fetched from [here][js url]. This, along with the [playground]: https://github.com/tree-sitter/tree-sitter/blob/master/docs/src/assets/js/playground.js [playground css]: https://github.com/tree-sitter/tree-sitter/blob/master/docs/src/assets/css/playground.css [podman]: https://podman.io -[preprocessor]: https://rust-lang.github.io/mdBook/for_developers/preprocessors.html [py package]: https://pypi.org/project/tree-sitter [py ts]: https://github.com/tree-sitter/py-tree-sitter [pypi]: https://pypi.org diff --git a/docs/src/7-playground.md b/docs/src/7-playground.md index 81c61805c..65b9cf433 100644 --- a/docs/src/7-playground.md +++ b/docs/src/7-playground.md @@ -96,9 +96,8 @@ You can also run playground locally (with your own grammar) using the CLI's tree-sitter playground subcommand.

-```admonish info -Logging (if enabled) can be viewed in the browser's console. -``` +> [!NOTE] +> Logging (if enabled) can be viewed in the browser's console.

The syntax tree should update as you type in the code. As you move around the code, the current node should be highlighted in the tree; you can also click any diff --git a/docs/src/assets/css/mdbook-admonish.css b/docs/src/assets/css/mdbook-admonish.css deleted file mode 100644 index 45aeff051..000000000 --- a/docs/src/assets/css/mdbook-admonish.css +++ /dev/null @@ -1,348 +0,0 @@ -@charset "UTF-8"; -:is(.admonition) { - display: flow-root; - margin: 1.5625em 0; - padding: 0 1.2rem; - color: var(--fg); - page-break-inside: avoid; - background-color: var(--bg); - border: 0 solid black; - border-inline-start-width: 0.4rem; - border-radius: 0.2rem; - box-shadow: 0 0.2rem 1rem rgba(0, 0, 0, 0.05), 0 0 0.1rem rgba(0, 0, 0, 0.1); -} -@media print { - :is(.admonition) { - box-shadow: none; - } -} -:is(.admonition) > * { - box-sizing: border-box; -} -:is(.admonition) :is(.admonition) { - margin-top: 1em; - margin-bottom: 1em; -} -:is(.admonition) > .tabbed-set:only-child { - margin-top: 0; -} -html :is(.admonition) > :last-child { - margin-bottom: 1.2rem; -} - -a.admonition-anchor-link { - display: none; - position: absolute; - left: -1.2rem; - padding-right: 1rem; -} -a.admonition-anchor-link:link, a.admonition-anchor-link:visited { - color: var(--fg); -} -a.admonition-anchor-link:link:hover, a.admonition-anchor-link:visited:hover { - text-decoration: none; -} -a.admonition-anchor-link::before { - content: "§"; -} - -:is(.admonition-title, summary.admonition-title) { - position: relative; - min-height: 4rem; - margin-block: 0; - margin-inline: -1.6rem -1.2rem; - padding-block: 0.8rem; - padding-inline: 4.4rem 1.2rem; - font-weight: 700; - background-color: rgba(68, 138, 255, 0.1); - print-color-adjust: exact; - -webkit-print-color-adjust: exact; - display: flex; -} -:is(.admonition-title, summary.admonition-title) p { - margin: 0; -} -html :is(.admonition-title, summary.admonition-title):last-child { - margin-bottom: 0; -} -:is(.admonition-title, summary.admonition-title)::before { - position: absolute; - top: 0.625em; - inset-inline-start: 1.6rem; - width: 2rem; - height: 2rem; - background-color: #448aff; - print-color-adjust: exact; - -webkit-print-color-adjust: exact; - mask-image: url('data:image/svg+xml;charset=utf-8,'); - -webkit-mask-image: url('data:image/svg+xml;charset=utf-8,'); - mask-repeat: no-repeat; - -webkit-mask-repeat: no-repeat; - mask-size: contain; - -webkit-mask-size: contain; - content: ""; -} -:is(.admonition-title, summary.admonition-title):hover a.admonition-anchor-link { - display: initial; -} - -details.admonition > summary.admonition-title::after { - position: absolute; - top: 0.625em; - inset-inline-end: 1.6rem; - height: 2rem; - width: 2rem; - background-color: currentcolor; - mask-image: var(--md-details-icon); - -webkit-mask-image: var(--md-details-icon); - mask-repeat: no-repeat; - -webkit-mask-repeat: no-repeat; - mask-size: contain; - -webkit-mask-size: contain; - content: ""; - transform: rotate(0deg); - transition: transform 0.25s; -} -details[open].admonition > summary.admonition-title::after { - transform: rotate(90deg); -} - -:root { - --md-details-icon: url("data:image/svg+xml;charset=utf-8,"); -} - -:root { - --md-admonition-icon--admonish-note: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-abstract: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-info: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-tip: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-success: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-question: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-warning: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-failure: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-danger: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-bug: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-example: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-quote: url("data:image/svg+xml;charset=utf-8,"); -} - -:is(.admonition):is(.admonish-note) { - border-color: #448aff; -} - -:is(.admonish-note) > :is(.admonition-title, summary.admonition-title) { - background-color: rgba(68, 138, 255, 0.1); -} -:is(.admonish-note) > :is(.admonition-title, summary.admonition-title)::before { - background-color: #448aff; - mask-image: var(--md-admonition-icon--admonish-note); - -webkit-mask-image: var(--md-admonition-icon--admonish-note); - mask-repeat: no-repeat; - -webkit-mask-repeat: no-repeat; - mask-size: contain; - -webkit-mask-repeat: no-repeat; -} - -:is(.admonition):is(.admonish-abstract, .admonish-summary, .admonish-tldr) { - border-color: #00b0ff; -} - -:is(.admonish-abstract, .admonish-summary, .admonish-tldr) > :is(.admonition-title, summary.admonition-title) { - background-color: rgba(0, 176, 255, 0.1); -} -:is(.admonish-abstract, .admonish-summary, .admonish-tldr) > :is(.admonition-title, summary.admonition-title)::before { - background-color: #00b0ff; - mask-image: var(--md-admonition-icon--admonish-abstract); - -webkit-mask-image: var(--md-admonition-icon--admonish-abstract); - mask-repeat: no-repeat; - -webkit-mask-repeat: no-repeat; - mask-size: contain; - -webkit-mask-repeat: no-repeat; -} - -:is(.admonition):is(.admonish-info, .admonish-todo) { - border-color: #00b8d4; -} - -:is(.admonish-info, .admonish-todo) > :is(.admonition-title, summary.admonition-title) { - background-color: rgba(0, 184, 212, 0.1); -} -:is(.admonish-info, .admonish-todo) > :is(.admonition-title, summary.admonition-title)::before { - background-color: #00b8d4; - mask-image: var(--md-admonition-icon--admonish-info); - -webkit-mask-image: var(--md-admonition-icon--admonish-info); - mask-repeat: no-repeat; - -webkit-mask-repeat: no-repeat; - mask-size: contain; - -webkit-mask-repeat: no-repeat; -} - -:is(.admonition):is(.admonish-tip, .admonish-hint, .admonish-important) { - border-color: #00bfa5; -} - -:is(.admonish-tip, .admonish-hint, .admonish-important) > :is(.admonition-title, summary.admonition-title) { - background-color: rgba(0, 191, 165, 0.1); -} -:is(.admonish-tip, .admonish-hint, .admonish-important) > :is(.admonition-title, summary.admonition-title)::before { - background-color: #00bfa5; - mask-image: var(--md-admonition-icon--admonish-tip); - -webkit-mask-image: var(--md-admonition-icon--admonish-tip); - mask-repeat: no-repeat; - -webkit-mask-repeat: no-repeat; - mask-size: contain; - -webkit-mask-repeat: no-repeat; -} - -:is(.admonition):is(.admonish-success, .admonish-check, .admonish-done) { - border-color: #00c853; -} - -:is(.admonish-success, .admonish-check, .admonish-done) > :is(.admonition-title, summary.admonition-title) { - background-color: rgba(0, 200, 83, 0.1); -} -:is(.admonish-success, .admonish-check, .admonish-done) > :is(.admonition-title, summary.admonition-title)::before { - background-color: #00c853; - mask-image: var(--md-admonition-icon--admonish-success); - -webkit-mask-image: var(--md-admonition-icon--admonish-success); - mask-repeat: no-repeat; - -webkit-mask-repeat: no-repeat; - mask-size: contain; - -webkit-mask-repeat: no-repeat; -} - -:is(.admonition):is(.admonish-question, .admonish-help, .admonish-faq) { - border-color: #64dd17; -} - -:is(.admonish-question, .admonish-help, .admonish-faq) > :is(.admonition-title, summary.admonition-title) { - background-color: rgba(100, 221, 23, 0.1); -} -:is(.admonish-question, .admonish-help, .admonish-faq) > :is(.admonition-title, summary.admonition-title)::before { - background-color: #64dd17; - mask-image: var(--md-admonition-icon--admonish-question); - -webkit-mask-image: var(--md-admonition-icon--admonish-question); - mask-repeat: no-repeat; - -webkit-mask-repeat: no-repeat; - mask-size: contain; - -webkit-mask-repeat: no-repeat; -} - -:is(.admonition):is(.admonish-warning, .admonish-caution, .admonish-attention) { - border-color: #ff9100; -} - -:is(.admonish-warning, .admonish-caution, .admonish-attention) > :is(.admonition-title, summary.admonition-title) { - background-color: rgba(255, 145, 0, 0.1); -} -:is(.admonish-warning, .admonish-caution, .admonish-attention) > :is(.admonition-title, summary.admonition-title)::before { - background-color: #ff9100; - mask-image: var(--md-admonition-icon--admonish-warning); - -webkit-mask-image: var(--md-admonition-icon--admonish-warning); - mask-repeat: no-repeat; - -webkit-mask-repeat: no-repeat; - mask-size: contain; - -webkit-mask-repeat: no-repeat; -} - -:is(.admonition):is(.admonish-failure, .admonish-fail, .admonish-missing) { - border-color: #ff5252; -} - -:is(.admonish-failure, .admonish-fail, .admonish-missing) > :is(.admonition-title, summary.admonition-title) { - background-color: rgba(255, 82, 82, 0.1); -} -:is(.admonish-failure, .admonish-fail, .admonish-missing) > :is(.admonition-title, summary.admonition-title)::before { - background-color: #ff5252; - mask-image: var(--md-admonition-icon--admonish-failure); - -webkit-mask-image: var(--md-admonition-icon--admonish-failure); - mask-repeat: no-repeat; - -webkit-mask-repeat: no-repeat; - mask-size: contain; - -webkit-mask-repeat: no-repeat; -} - -:is(.admonition):is(.admonish-danger, .admonish-error) { - border-color: #ff1744; -} - -:is(.admonish-danger, .admonish-error) > :is(.admonition-title, summary.admonition-title) { - background-color: rgba(255, 23, 68, 0.1); -} -:is(.admonish-danger, .admonish-error) > :is(.admonition-title, summary.admonition-title)::before { - background-color: #ff1744; - mask-image: var(--md-admonition-icon--admonish-danger); - -webkit-mask-image: var(--md-admonition-icon--admonish-danger); - mask-repeat: no-repeat; - -webkit-mask-repeat: no-repeat; - mask-size: contain; - -webkit-mask-repeat: no-repeat; -} - -:is(.admonition):is(.admonish-bug) { - border-color: #f50057; -} - -:is(.admonish-bug) > :is(.admonition-title, summary.admonition-title) { - background-color: rgba(245, 0, 87, 0.1); -} -:is(.admonish-bug) > :is(.admonition-title, summary.admonition-title)::before { - background-color: #f50057; - mask-image: var(--md-admonition-icon--admonish-bug); - -webkit-mask-image: var(--md-admonition-icon--admonish-bug); - mask-repeat: no-repeat; - -webkit-mask-repeat: no-repeat; - mask-size: contain; - -webkit-mask-repeat: no-repeat; -} - -:is(.admonition):is(.admonish-example) { - border-color: #7c4dff; -} - -:is(.admonish-example) > :is(.admonition-title, summary.admonition-title) { - background-color: rgba(124, 77, 255, 0.1); -} -:is(.admonish-example) > :is(.admonition-title, summary.admonition-title)::before { - background-color: #7c4dff; - mask-image: var(--md-admonition-icon--admonish-example); - -webkit-mask-image: var(--md-admonition-icon--admonish-example); - mask-repeat: no-repeat; - -webkit-mask-repeat: no-repeat; - mask-size: contain; - -webkit-mask-repeat: no-repeat; -} - -:is(.admonition):is(.admonish-quote, .admonish-cite) { - border-color: #9e9e9e; -} - -:is(.admonish-quote, .admonish-cite) > :is(.admonition-title, summary.admonition-title) { - background-color: rgba(158, 158, 158, 0.1); -} -:is(.admonish-quote, .admonish-cite) > :is(.admonition-title, summary.admonition-title)::before { - background-color: #9e9e9e; - mask-image: var(--md-admonition-icon--admonish-quote); - -webkit-mask-image: var(--md-admonition-icon--admonish-quote); - mask-repeat: no-repeat; - -webkit-mask-repeat: no-repeat; - mask-size: contain; - -webkit-mask-repeat: no-repeat; -} - -.navy :is(.admonition) { - background-color: var(--sidebar-bg); -} - -.ayu :is(.admonition), -.coal :is(.admonition) { - background-color: var(--theme-hover); -} - -.rust :is(.admonition) { - background-color: var(--sidebar-bg); - color: var(--sidebar-fg); -} -.rust .admonition-anchor-link:link, .rust .admonition-anchor-link:visited { - color: var(--sidebar-fg); -} diff --git a/docs/src/cli/init-config.md b/docs/src/cli/init-config.md index 77aacd666..8359996f0 100644 --- a/docs/src/cli/init-config.md +++ b/docs/src/cli/init-config.md @@ -11,9 +11,8 @@ 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` -```admonish info -The CLI will work if there's no config file present, falling back on default values for each configuration option. -``` +> [!NOTE] +> 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. @@ -117,9 +116,8 @@ An example theme can be seen below: 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. -```admonish note -Omitting a field will cause the relevant text to be rendered with its default color. -``` +> [!NOTE] +> Omitting a field will cause the relevant text to be rendered with its default color. An example parse theme can be seen below: diff --git a/docs/src/cli/playground.md b/docs/src/cli/playground.md index c0bfb4954..45ac3867f 100644 --- a/docs/src/cli/playground.md +++ b/docs/src/cli/playground.md @@ -6,10 +6,9 @@ The `playground` command allows you to start a local playground to test your par tree-sitter playground [OPTIONS] # Aliases: play, pg, web-ui ``` -```admonish note -For this to work, 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`). -``` +> [!NOTE] +> For this to work, 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 diff --git a/docs/src/cli/test.md b/docs/src/cli/test.md index 70bc09367..f90e01205 100644 --- a/docs/src/cli/test.md +++ b/docs/src/cli/test.md @@ -36,9 +36,8 @@ If `--lib-path` is used, the name of the language used to extract the library's Update the expected output of tests. -```admonish info -Tests containing `ERROR` nodes or `MISSING` nodes will not be updated. -``` +> [!NOTE] +> Tests containing `ERROR` nodes or `MISSING` nodes will not be updated. ### `-d/--debug` diff --git a/docs/src/creating-parsers/1-getting-started.md b/docs/src/creating-parsers/1-getting-started.md index b369c6d82..2fe8ea16f 100644 --- a/docs/src/creating-parsers/1-getting-started.md +++ b/docs/src/creating-parsers/1-getting-started.md @@ -37,13 +37,11 @@ mkdir tree-sitter-${LOWER_PARSER_NAME} cd tree-sitter-${LOWER_PARSER_NAME} ``` -```admonish note -The `LOWER_` prefix here means the "lowercase" name of the language. -``` +> [!NOTE] +> The `LOWER_` prefix here means the "lowercase" name of the language. -```admonish warning -Dashes are not permitted via the CLI's `init` command and should not be used in parser names. -``` +> [!WARNING] +> Dashes are not permitted via the CLI's `init` command and should not be used in parser names. ### Init @@ -78,10 +76,9 @@ export default grammar({ }); ``` -```admonish info -The placeholders shown above would be replaced with the corresponding data you provided in the `init` sub-command's -prompts. -``` +> [!NOTE] +> The placeholders shown above would be replaced with the corresponding data you provided in the `init` sub-command's +> prompts. To learn more about this command, check the [reference page](../cli/init.md). diff --git a/docs/src/creating-parsers/2-the-grammar-dsl.md b/docs/src/creating-parsers/2-the-grammar-dsl.md index 820de60cd..eb116975c 100644 --- a/docs/src/creating-parsers/2-the-grammar-dsl.md +++ b/docs/src/creating-parsers/2-the-grammar-dsl.md @@ -20,20 +20,19 @@ DSL through the `RustRegex` class. Simply pass your regex pattern as a string: accepts a single pattern string. While it doesn't support separate flags, you can use inline flags within the pattern itself. For more details about Rust's regex syntax and capabilities, check out the [Rust regex documentation][rust regex]. - ```admonish note - Only a subset of the Regex engine is actually supported. This is due to certain features like lookahead and lookaround - assertions not being feasible to use in an LR(1) grammar, as well as certain flags being unnecessary for tree-sitter. However, - plenty of features are supported by default: - - - Character classes - - Character ranges - - Character sets - - Quantifiers - - Alternation - - Grouping - - Unicode character escapes - - Unicode property escapes - ``` + > [!NOTE] + > Only a subset of the Regex engine is actually supported. This is due to certain features like lookahead and lookaround + > assertions not being feasible to use in an LR(1) grammar, as well as certain flags being unnecessary for tree-sitter. However, + > plenty of features are supported by default: + > + > - Character classes + > - Character ranges + > - Character sets + > - Quantifiers + > - Alternation + > - Grouping + > - Unicode character escapes + > - Unicode property escapes - **Sequences : `seq(rule1, rule2, ...)`** — This function creates a rule that matches any number of other rules, one after another. It is analogous to simply writing multiple symbols next to each other in [EBNF notation][ebnf]. diff --git a/docs/src/creating-parsers/3-writing-the-grammar.md b/docs/src/creating-parsers/3-writing-the-grammar.md index b938756ba..b5e5c5298 100644 --- a/docs/src/creating-parsers/3-writing-the-grammar.md +++ b/docs/src/creating-parsers/3-writing-the-grammar.md @@ -244,11 +244,10 @@ Possible resolutions: 4: Add a conflict for these rules: `binary_expression` `unary_expression` ``` -```admonish hint -The • character in the error message indicates where exactly during -parsing the conflict occurs, or in other words, where the parser is encountering -ambiguity. -``` +> [!TIP] +> The • character in the error message indicates where exactly during +> parsing the conflict occurs, or in other words, where the parser is encountering +> ambiguity. For an expression like `-a * b`, it's not clear whether the `-` operator applies to the `a * b` or just to the `a`. This is where the `prec` function [described in the previous page][grammar dsl] comes into play. By wrapping a rule with `prec`, @@ -364,11 +363,10 @@ In such cases, we want the parser to explore both possibilities by explicitly de } ``` -```admonish note -The example is a bit contrived for the purpose of illustrating the usage of conflicts. The actual JavaScript grammar isn't -structured like that, but this conflict is actually present in the -[Tree-sitter JavaScript grammar](https://github.com/tree-sitter/tree-sitter-javascript/blob/108b2d4d17a04356a340aea809e4dd5b801eb40d/grammar.js#L100). -``` +> [!NOTE] +> The example is a bit contrived for the purpose of illustrating the usage of conflicts. The actual JavaScript grammar isn't +> structured like that, but this conflict is actually present in the +> [Tree-sitter JavaScript grammar](https://github.com/tree-sitter/tree-sitter-javascript/blob/108b2d4d17a04356a340aea809e4dd5b801eb40d/grammar.js#L100). ## Hiding Rules @@ -420,11 +418,10 @@ module.exports = grammar({ }); ``` -```admonish warning -When adding more complicated tokens to `extras`, it's preferable to associate the pattern -with a rule. This way, you avoid the lexer inlining this pattern in a bunch of spots, -which can dramatically reduce the parser size. -``` +> [!WARNING] +> When adding more complicated tokens to `extras`, it's preferable to associate the pattern +> with a rule. This way, you avoid the lexer inlining this pattern in a bunch of spots, +> which can dramatically reduce the parser size. For example, instead of defining the `comment` token inline in `extras`: @@ -471,10 +468,9 @@ module.exports = grammar({ }); ``` -```admonish note -Tree-sitter intentionally simplifies the whitespace character class, `\s`, to `[ \t\n\r]` as a performance -optimization. This is because typically users do not require the full Unicode definition of whitespace. -``` +> [!NOTE] +> Tree-sitter intentionally simplifies the whitespace character class, `\s`, to `[ \t\n\r]` as a performance +> optimization. This is because typically users do not require the full Unicode definition of whitespace. ## Using Supertypes @@ -520,12 +516,11 @@ module.exports = grammar({ Although supertype rules are hidden from the syntax tree, they can still be used in queries. See the chapter on [Query Syntax][query syntax] for more information. -```admonish warning -Aliasing a supertype rule makes the node in the alias match the supertype in -name only and will not be treated as a supertype. For `alias($.foo, $.bar)` a -query targeting `bar` will not transparently match the supertype's subtypes the -way a query targeting `foo` would. -``` +> [!WARNING] +> Aliasing a supertype rule makes the node in the alias match the supertype in +> name only and will not be treated as a supertype. For `alias($.foo, $.bar)` a +> query targeting `bar` will not transparently match the supertype's subtypes the +> way a query targeting `foo` would. # Lexical Analysis @@ -637,11 +632,10 @@ It would then correctly recognize the code as invalid. Aside from improving error detection, keyword extraction also has performance benefits. It allows Tree-sitter to generate a smaller, simpler lexing function, which means that **the parser will compile much more quickly**. -```admonish note -The word token must be a unique token that is not reused by another rule. If you want to have a word token used in a -rule that's called something else, you should just alias the word token instead, like how the Rust grammar does it -here -``` +> [!NOTE] +> The word token must be a unique token that is not reused by another rule. If you want to have a word token used in a +> rule that's called something else, you should just alias the word token instead, like how the Rust grammar does it +> here [ambiguous-grammar]: https://en.wikipedia.org/wiki/Ambiguous_grammar [antlr]: https://www.antlr.org diff --git a/docs/src/creating-parsers/4-external-scanners.md b/docs/src/creating-parsers/4-external-scanners.md index 3e1b4e307..1192ce612 100644 --- a/docs/src/creating-parsers/4-external-scanners.md +++ b/docs/src/creating-parsers/4-external-scanners.md @@ -224,11 +224,10 @@ array macros from `tree_sitter/array.h`. There are quite a few of them provided for you, but here's how you could get started tracking some state. Check out the header itself for more detailed documentation. -```admonish attention -Do not use any of the array functions or macros that are prefixed with an underscore and have comments saying -that it is not what you are looking for. These are internal functions used as helpers by other macros that are public. -They are not meant to be used directly, nor are they what you want. -``` +> [!WARNING] +> Do not use any of the array functions or macros that are prefixed with an underscore and have comments saying +> that it is not what you are looking for. These are internal functions used as helpers by other macros that are public. +> They are not meant to be used directly, nor are they what you want. ```c #include "tree_sitter/parser.h" @@ -370,13 +369,12 @@ However, when you use rule references (like `$.if_keyword`) in the externals arr in the grammar, Tree-sitter cannot fall back to its internal lexer. In this case, the external scanner is solely responsible for recognizing these tokens. -```admonish danger -- External scanners can easily create infinite loops - -- Be extremely careful when emitting zero-width tokens - -- Always use the `eof` function when looping through characters -``` +> [!CAUTION] +> - External scanners can easily create infinite loops +> +> - Be extremely careful when emitting zero-width tokens +> +> - Always use the `eof` function when looping through characters [ejs]: https://ejs.co [enum]: https://en.wikipedia.org/wiki/Enumerated_type#C diff --git a/docs/src/creating-parsers/5-writing-tests.md b/docs/src/creating-parsers/5-writing-tests.md index c95b5f5d7..100409e21 100644 --- a/docs/src/creating-parsers/5-writing-tests.md +++ b/docs/src/creating-parsers/5-writing-tests.md @@ -33,10 +33,9 @@ func x() int { * Then, the **expected output syntax tree** is written as an [S-expression][s-exp]. The exact placement of whitespace in the S-expression doesn't matter, but ideally the syntax tree should be legible. -```admonish tip -The S-expression does not show syntax nodes like `func`, `(` and `;`, which are expressed as strings and regexes in the grammar. -It only shows the *named* nodes, as described in [this section][named-vs-anonymous-nodes] of the page on parser usage. -``` +> [!TIP] +> The S-expression does not show syntax nodes like `func`, `(` and `;`, which are expressed as strings and regexes in the grammar. +> It only shows the *named* nodes, as described in [this section][named-vs-anonymous-nodes] of the page on parser usage. The expected output section can also *optionally* show the [*field names*][node-field-names] associated with each child node. To include field names in your tests, you write a node's field name followed by a colon, before the node itself @@ -109,20 +108,18 @@ The recommendation is to be comprehensive in adding tests. If it's a visible nod directory. It's typically a good idea to test all the permutations of each language construct. This increases test coverage, but doubly acquaints readers with a way to examine expected outputs and understand the "edges" of a language. -```admonish tip -After modifying the grammar, you can run `tree-sitter test -u` -to update all syntax trees in corpus files with current parser output. -``` +> [!TIP] +> After modifying the grammar, you can run `tree-sitter test -u` +> to update all syntax trees in corpus files with current parser output. ## Attributes Tests can be annotated with a few `attributes`. Attributes must be put in the header, below the test name, and start with a `:`. A couple of attributes also take in a parameter, which require the use of parenthesis. -```admonish tip -If you'd like to supply in multiple parameters, e.g. to run tests on multiple platforms or to test multiple languages, -you can repeat the attribute on a new line. -``` +> [!TIP] +> If you'd like to supply in multiple parameters, e.g. to run tests on multiple platforms or to test multiple languages, +> you can repeat the attribute on a new line. The following attributes are available: diff --git a/docs/src/using-parsers/2-basic-parsing.md b/docs/src/using-parsers/2-basic-parsing.md index 8c425d6b2..fb12a1740 100644 --- a/docs/src/using-parsers/2-basic-parsing.md +++ b/docs/src/using-parsers/2-basic-parsing.md @@ -54,9 +54,8 @@ typedef uint32_t (*TSDecodeFunction)( ); ``` -```admonish attention -The `TSInputEncoding` must be set to `TSInputEncodingCustom` for the `decode` function to be called. -``` +> [!WARNING] +> The `TSInputEncoding` must be set to `TSInputEncodingCustom` for the `decode` function to be called. The `string` argument is a pointer to the text to decode, which comes from the `read` function, and the `length` argument is the length of the `string`. The `code_point` argument is a pointer to an integer that represents the decoded code point, @@ -87,9 +86,8 @@ TSPoint ts_node_start_point(TSNode); TSPoint ts_node_end_point(TSNode); ``` -```admonish note -A *newline* is considered to be a single line feed (`\n`) character. -``` +> [!NOTE] +> A *newline* is considered to be a single line feed (`\n`) character. ## Retrieving Nodes diff --git a/docs/src/using-parsers/3-advanced-parsing.md b/docs/src/using-parsers/3-advanced-parsing.md index c1c92e241..50582c82c 100644 --- a/docs/src/using-parsers/3-advanced-parsing.md +++ b/docs/src/using-parsers/3-advanced-parsing.md @@ -156,9 +156,8 @@ Internally, copying a syntax tree just entails incrementing an atomic reference tree which you can freely query, edit, reparse, or delete on a new thread while continuing to use the original tree on a different thread. -```admonish danger -Individual `TSTree` instances are _not_ thread safe; you must copy a tree if you want to use it on multiple threads simultaneously. -``` +> [!CAUTION] +> Individual `TSTree` instances are _not_ thread safe; you must copy a tree if you want to use it on multiple threads simultaneously. [ejs]: https://ejs.co [erb]: https://ruby-doc.org/stdlib-2.5.1/libdoc/erb/rdoc/ERB.html diff --git a/docs/src/using-parsers/4-walking-trees.md b/docs/src/using-parsers/4-walking-trees.md index 94ac4eb4c..30c8d9a88 100644 --- a/docs/src/using-parsers/4-walking-trees.md +++ b/docs/src/using-parsers/4-walking-trees.md @@ -4,13 +4,12 @@ You can access every node in a syntax tree using the `TSNode` APIs [described ea to access a large number of nodes, the fastest way to do so is with a _tree cursor_. A cursor is a stateful object that allows you to walk a syntax tree with maximum efficiency. -```admonish note -The given input node is considered the root of the cursor, and the cursor cannot walk outside this node. -Going to the parent or any sibling of the root node will always return `false`. - -This has no unexpected effects if the given input node is the actual `root` node of the tree, but is something to keep in -mind when using cursors constructed with a node that is not the `root` node. -``` +> [!NOTE] +> The given input node is considered the root of the cursor, and the cursor cannot walk outside this node. +> Going to the parent or any sibling of the root node will always return `false`. +> +> This has no unexpected effects if the given input node is the actual `root` node of the tree, but is something to keep in +> mind when using cursors constructed with a node that is not the `root` node. You can initialize a cursor from any node: diff --git a/docs/src/using-parsers/queries/3-predicates-and-directives.md b/docs/src/using-parsers/queries/3-predicates-and-directives.md index 546bde416..862664a52 100644 --- a/docs/src/using-parsers/queries/3-predicates-and-directives.md +++ b/docs/src/using-parsers/queries/3-predicates-and-directives.md @@ -186,15 +186,14 @@ To recap about the predicates and directives Tree-sitter's bindings support: - `#strip!` removes text from a capture -```admonish info -Predicates and directives are not handled directly by the Tree-sitter C library. -They are just exposed in a structured form so that higher-level code can perform -the filtering. However, higher-level bindings to Tree-sitter like -[the Rust Crate][rust crate] -or the [WebAssembly binding][wasm binding] -do implement a few common predicates like those explained above. In the future, more "standard" predicates and directives -may be added. -``` +> [!NOTE] +> Predicates and directives are not handled directly by the Tree-sitter C library. +> They are just exposed in a structured form so that higher-level code can perform +> the filtering. However, higher-level bindings to Tree-sitter like +> [the Rust Crate][rust crate] +> or the [WebAssembly binding][wasm binding] +> do implement a few common predicates like those explained above. In the future, more "standard" predicates and directives +> may be added. [cgo]: https://pkg.go.dev/cmd/cgo [rust crate]: https://github.com/tree-sitter/tree-sitter/tree/master/lib/binding_rust diff --git a/docs/src/using-parsers/queries/4-api.md b/docs/src/using-parsers/queries/4-api.md index 15f16adf4..32193b879 100644 --- a/docs/src/using-parsers/queries/4-api.md +++ b/docs/src/using-parsers/queries/4-api.md @@ -79,7 +79,6 @@ bool ts_query_cursor_set_containing_byte_range(TSQueryCursor *self, uint32_t sta bool ts_query_cursor_set_containing_point_range(TSQueryCursor *self, TSPoint start_point, TSPoint end_point); ``` -```admonish note -For all of these functions, an end value of zero is treated as unbounded (the maximum possible value). -This means passing a byte range of `(0, 0)` (or a point range of `{0, 0}, {0, 0}`) will match the entire tree, not an empty range. -``` +> [!NOTE] +> For all of these functions, an end value of zero is treated as unbounded (the maximum possible value). +> This means passing a byte range of `(0, 0)` (or a point range of `{0, 0}, {0, 0}`) will match the entire tree, not an empty range.