From 21d74b848287ef84fd4f68ca854a7469e77828e6 Mon Sep 17 00:00:00 2001 From: Amaan Qureshi Date: Fri, 10 Jan 2025 02:29:32 -0500 Subject: [PATCH] docs: add mdbook-admonish for better tooltips --- docs/book.toml | 11 +- docs/src/3-syntax-highlighting.md | 27 +- docs/src/7-playground.md | 8 +- docs/src/assets/css/mdbook-admonish.css | 348 ++++++++++++++++++ docs/src/cli/init-config.md | 14 +- docs/src/cli/playground.md | 4 +- docs/src/cli/test.md | 6 +- .../src/creating-parsers/1-getting-started.md | 8 +- .../creating-parsers/3-writing-the-grammar.md | 4 +- .../creating-parsers/4-external-scanners.md | 18 +- docs/src/creating-parsers/5-writing-tests.md | 13 +- docs/src/using-parsers/2-basic-parsing.md | 4 +- docs/src/using-parsers/3-advanced-parsing.md | 7 +- docs/src/using-parsers/4-walking-trees.md | 7 +- .../queries/3-predicates-and-directives.md | 4 +- 15 files changed, 435 insertions(+), 48 deletions(-) create mode 100644 docs/src/assets/css/mdbook-admonish.css diff --git a/docs/book.toml b/docs/book.toml index f08f55f5..664a1f24 100644 --- a/docs/book.toml +++ b/docs/book.toml @@ -9,7 +9,10 @@ src = "src" title = "Tree-sitter" [output.html] -additional-css = ["src/assets/css/playground.css"] +additional-css = [ + "src/assets/css/playground.css", + "src/assets/css/mdbook-admonish.css", +] additional-js = ["src/assets/js/playground.js"] git-repository-url = "https://github.com/tree-sitter/tree-sitter" git-repository-icon = "fa-github" @@ -22,3 +25,9 @@ boost-title = 2 boost-hierarchy = 2 boost-paragraph = 1 expand = true + +[preprocessor] + +[preprocessor.admonish] +command = "mdbook-admonish" +assets_version = "3.0.2" # do not edit: managed by `mdbook-admonish install` diff --git a/docs/src/3-syntax-highlighting.md b/docs/src/3-syntax-highlighting.md index 09db494e..b11a2e86 100644 --- a/docs/src/3-syntax-highlighting.md +++ b/docs/src/3-syntax-highlighting.md @@ -155,11 +155,13 @@ 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'
+
 func increment(a int) int {
     return a + 1
 }
 

+```
 
 ### Local Variables
 
@@ -286,7 +288,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'
+
 def process_list(list)
   context = current_context
   list.map do |item|
@@ -297,6 +300,7 @@ Running `tree-sitter highlight` on this ruby file would produce output like this
 item = 5
 list = [item]
 

+```
 
 ### Language Injection
 
@@ -404,18 +408,19 @@ var abc = function(d) {
 };
 ```
 
-From the Sublime text docs:
+```admonish cite title='From the Sublime text docs'
+The two types of tests are:
 
-> 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.
 
-Note that an exclamation mark (`!`) can be used to negate a selector. For example, `!keyword` will match any scope that is
+**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.
+```
 
 [erb]: https://en.wikipedia.org/wiki/ERuby
 [highlight crate]: https://github.com/tree-sitter/tree-sitter/tree/master/highlight
diff --git a/docs/src/7-playground.md b/docs/src/7-playground.md
index 0205805c..5892be7b 100644
--- a/docs/src/7-playground.md
+++ b/docs/src/7-playground.md
@@ -81,9 +81,11 @@
 You can also run playground locally (with your own grammar) using the
 CLI's tree-sitter playground subcommand.
 

-

-
Note: Logging (if enabled) can be viewed in the browser's console.

-

+
+```admonish info
+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
 node in the tree to select the corresponding part of the code.

diff --git a/docs/src/assets/css/mdbook-admonish.css b/docs/src/assets/css/mdbook-admonish.css
new file mode 100644
index 00000000..45aeff05
--- /dev/null
+++ b/docs/src/assets/css/mdbook-admonish.css
@@ -0,0 +1,348 @@
+@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 3af0e975..96cb96a7 100644
--- a/docs/src/cli/init-config.md
+++ b/docs/src/cli/init-config.md
@@ -11,8 +11,9 @@ 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.
+```admonish info
+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.
@@ -113,8 +114,13 @@ An example theme can be seen below:
 ## `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.
+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.
+```
+
+An example parse theme can be seen below:
 
 ```json
 {
diff --git a/docs/src/cli/playground.md b/docs/src/cli/playground.md
index 75ff88e7..75ab4588 100644
--- a/docs/src/cli/playground.md
+++ b/docs/src/cli/playground.md
@@ -6,8 +6,10 @@ The `playground` command allows you to start a local playground to test your par
 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
+```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`).
+```
 
 ## Options
 
diff --git a/docs/src/cli/test.md b/docs/src/cli/test.md
index 187b9643..826b6660 100644
--- a/docs/src/cli/test.md
+++ b/docs/src/cli/test.md
@@ -18,7 +18,11 @@ 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.
+Update the expected output of tests. 
+
+```admonish info
+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 0dad6dd4..6cab1839 100644
--- a/docs/src/creating-parsers/1-getting-started.md
+++ b/docs/src/creating-parsers/1-getting-started.md
@@ -37,7 +37,9 @@ mkdir tree-sitter-${LOWER_PARSER_NAME}
 cd tree-sitter-${LOWER_PARSER_NAME}
 ```
 
-Note that the `LOWER-` prefix here means the "lowercase" name of the language.
+```admonish note
+The `LOWER-` prefix here means the "lowercase" name of the language.
+```
 
 ### Init
 
@@ -72,8 +74,10 @@ module.exports = grammar({
 });
 ```
 
-Note that the placeholders shown above would be replaced with the corresponding data you provided in the `init` sub-command's
+```admonish info
+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/3-writing-the-grammar.md b/docs/src/creating-parsers/3-writing-the-grammar.md
index f86cacd6..837a0691 100644
--- a/docs/src/creating-parsers/3-writing-the-grammar.md
+++ b/docs/src/creating-parsers/3-writing-the-grammar.md
@@ -228,11 +228,11 @@ 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.
-

+```
 
 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`,
diff --git a/docs/src/creating-parsers/4-external-scanners.md b/docs/src/creating-parsers/4-external-scanners.md
index e1d9f9ad..7d63d04b 100644
--- a/docs/src/creating-parsers/4-external-scanners.md
+++ b/docs/src/creating-parsers/4-external-scanners.md
@@ -224,11 +224,11 @@ 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 . 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.
-

+```
 
 ```c
 #include "tree_sitter/parser.h"
@@ -369,17 +369,13 @@ 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
 
-**Important Warnings**
+- Be extremely careful when emitting zero-width tokens
 
-⚠️ External scanners can easily create infinite loops
-
-⚠️ Be extremely careful when emitting zero-width tokens
-
-⚠️ Always use the `eof` function when looping through characters
-
-

+- 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 f8c1ac91..5589055d 100644
--- a/docs/src/creating-parsers/5-writing-tests.md
+++ b/docs/src/creating-parsers/5-writing-tests.md
@@ -31,9 +31,12 @@ func x() int {
 * Then the **input source code** is written, followed by a line containing three or more `-` (dash) characters.
 
 * 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. Note that 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 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.
+```
 
   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 in
@@ -89,8 +92,10 @@ but doubly acquaints readers with a way to examine expected outputs and understa
 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.
 
-**Note**: If you'd like to supply in multiple parameters, e.g. to run tests on multiple platforms or to test multiple languages,
+```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.
+```
 
 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 795ff611..f9b0fb3f 100644
--- a/docs/src/using-parsers/2-basic-parsing.md
+++ b/docs/src/using-parsers/2-basic-parsing.md
@@ -53,7 +53,9 @@ typedef uint32_t (*DecodeFunction)(
 );
 ```
 
-> Note that the `TSInputEncoding` must be set to `TSInputEncodingCustom` for the `decode` function to be called.
+```admonish attention
+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,
diff --git a/docs/src/using-parsers/3-advanced-parsing.md b/docs/src/using-parsers/3-advanced-parsing.md
index dbab046b..df13fe30 100644
--- a/docs/src/using-parsers/3-advanced-parsing.md
+++ b/docs/src/using-parsers/3-advanced-parsing.md
@@ -154,8 +154,11 @@ TSTree *ts_tree_copy(const TSTree *);
 
 Internally, copying a syntax tree just entails incrementing an atomic reference count. Conceptually, it provides you a new
 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. Note that individual `TSTree` instances are _not_ thread safe; you must copy a tree if you want to use
-it on multiple threads simultaneously.
+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.
+```
 
 [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 33da38e1..94ac4eb4 100644
--- a/docs/src/using-parsers/4-walking-trees.md
+++ b/docs/src/using-parsers/4-walking-trees.md
@@ -4,14 +4,13 @@ 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.
 
-

-
-Note that the given input node is considered the root of the cursor, and the cursor cannot walk outside this node.
+```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.
-

+```
 
 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 23244969..a059a3ba 100644
--- a/docs/src/using-parsers/queries/3-predicates-and-directives.md
+++ b/docs/src/using-parsers/queries/3-predicates-and-directives.md
@@ -186,13 +186,15 @@ To recap about the predicates and directives Tree-Sitter's bindings support:
 
 - `#strip!` removes text from a capture
 
-_Note_ — Predicates and directives are not handled directly by the Tree-sitter C library.
+```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.
+```
 
 [cgo]: https://pkg.go.dev/cmd/cgo
 [rust crate]: https://github.com/tree-sitter/tree-sitter/tree/master/lib/binding_rust