Add docs on highlighting

This commit is contained in:
Jonatan Kłosko 2021-09-29 20:33:13 +02:00
parent 7357885bbc
commit 01d428d3a6
4 changed files with 82 additions and 13 deletions

View File

@ -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.

60
docs/highlighting.md Normal file
View File

@ -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
```

19
docs/index.md Normal file
View File

@ -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)

View File

@ -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