From 01d428d3a6b6b4bcde1f5a3af2926dcd9d1d616a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jonatan=20K=C5=82osko?= <jonatanklosko@gmail.com>
Date: Wed, 29 Sep 2021 20:33:13 +0200
Subject: [PATCH] Add docs on highlighting

---
 README.md                 |  2 +-
 docs/highlighting.md      | 60 +++++++++++++++++++++++++++++++++++++++
 docs/index.md             | 19 +++++++++++++
 docs.md => docs/parser.md | 14 ++-------
 4 files changed, 82 insertions(+), 13 deletions(-)
 create mode 100644 docs/highlighting.md
 create mode 100644 docs/index.md
 rename docs.md => docs/parser.md (94%)

diff --git a/README.md b/README.md
index 1f54164..e9fbc47 100644
--- a/README.md
+++ b/README.md
@@ -6,4 +6,4 @@ Elixir grammar for [tree-sitter](https://github.com/tree-sitter/tree-sitter).
 
 ## Development
 
-See [the docs](./docs.md) for development notes.
+See [the docs](./docs/index.md) for more details.
diff --git a/docs/highlighting.md b/docs/highlighting.md
new file mode 100644
index 0000000..3fd989f
--- /dev/null
+++ b/docs/highlighting.md
@@ -0,0 +1,60 @@
+# Syntax highlighting
+
+For detailed introduction see the official guide on [Syntax highlighting](https://tree-sitter.github.io/tree-sitter/syntax-highlighting).
+
+Briefly speaking, Tree-sitter uses the rules in `queries/highlights.scm` to annotate nodes
+with specific tokens, then it maps those tokens to formatting style according to user-defined
+theme.
+
+To test highlighting using the CLI, you need to create local configuration.
+
+```shell
+# Create the config file
+npx tree-sitter init-config
+```
+
+The above command should print out the config location, so that you can further configure it.
+Open the file and modify `"parser-directories"` to include the parent directory of `tree-sitter-elixir`.
+Also, you can optionally customize the theme, here's a tiny subset of the One Dark theme:
+
+```json
+{
+  "number": {
+    "color": "#61afef",
+    "bold": true
+  },
+  "string": "#98c379",
+  "string.escape": "#56b6c2",
+  "string.special": "#61afef",
+  "string.regexp": "#e06c75",
+  "type": "#e06c75",
+  "comment": {
+    "color": "#5c6370",
+    "italic": true
+  },
+  "punctuation": "#abb2bf",
+  "punctuation.special": "#be5046",
+  "operator": {
+    "color": "#d19a66",
+    "bold": true
+  },
+  "variable": "#abb2bf",
+  "function": "#61afef",
+  "constant": "#61afef",
+  "constant.builtin": {
+    "color": "#e06c75",
+    "bold": true
+  },
+  "keyword": "#c678dd",
+  "attribute": "#e06c75",
+  "embedded": null
+}
+```
+
+With this setup you can test highlighting on files using the Tree-sitter CLI.
+
+```shell
+npx tree-sitter highlight tmp/test.ex
+
+npx tree-sitter highlight test/highlight/**/*.ex
+```
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..9bdf1c6
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,19 @@
+# Development notes
+
+This documentation covers rationale behind some of the design and implementation decisions,
+as well as basic Tree-sitter tips that are relevant.
+
+## Pages
+
+* [Parser](./parser.md)
+* [Highlighting](./highlighting.md)
+
+## Acknowledgements
+
+While this parser is written from scratch, there were previous efforts that made
+for a helpful reference:
+
+* [tree-sitter-elixir](https://github.com/ananthakumaran/tree-sitter-elixir) developed
+  by [@ananthakumaran](https://github.com/ananthakumaran)
+* [tree-sitter-elixir](https://github.com/wingyplus/tree-sitter-elixir) developed
+  by [@wingyplus](https://github.com/wingyplus) and [@Tuxified](https://github.com/Tuxified)
diff --git a/docs.md b/docs/parser.md
similarity index 94%
rename from docs.md
rename to docs/parser.md
index 6d014ef..83965a4 100644
--- a/docs.md
+++ b/docs/parser.md
@@ -1,14 +1,4 @@
-# Development notes
-
-## Acknowledgements
-
-While this parser is written from scratch, there were previous efforts that made
-for a helpful reference:
-
-* [tree-sitter-elixir](https://github.com/ananthakumaran/tree-sitter-elixir) developed
-  by [@ananthakumaran](https://github.com/ananthakumaran)
-* [tree-sitter-elixir](https://github.com/wingyplus/tree-sitter-elixir) developed
-  by [@wingyplus](https://github.com/wingyplus) and [@Tuxified](https://github.com/Tuxified)
+# Parser
 
 ## The AST
 
@@ -39,7 +29,7 @@ like, have a look at the tests in `test/corpus/`.
 
 ## Getting started with Tree-sitter
 
-For official notes see the official guide on [Creating parsers](https://tree-sitter.github.io/tree-sitter/creating-parsers).
+For detailed introduction see the official guide on [Creating parsers](https://tree-sitter.github.io/tree-sitter/creating-parsers).
 
 Essentially, we define relevant language rules in `grammar.js`, based on which
 Tree-sitter generates parser code (under `src/`). In some cases, we want to write