mirror of
https://github.com/nvim-treesitter/nvim-treesitter.git
synced 2026-07-17 10:50:06 -04:00
Docs: format and fixes
Format the docs to be consisted and some typos.
This commit is contained in:
Santos Gallegos
Thomas Vigouroux
parent
1301884e97
commit
6f9e5bf23f
3 changed files with 235 additions and 176 deletions
119
README.md
119
README.md
|
|
@ -4,7 +4,9 @@ Traditionnal highlighting (left) vs Treesitter-based highlighting (right).
|
|||
[](https://gitter.im/nvim-treesitter/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
|
||||
|
||||
|
||||
|
||||
# nvim-treesitter
|
||||
|
||||
Treesitter configurations and abstraction layer for Neovim.
|
||||
|
||||
**Warning: Treesitter and Treesitter highlighting are an experimental feature of nightly versions of Neovim.
|
||||
|
|
@ -13,9 +15,10 @@ Please consider the experience with this plug-in as experimental until Neovim 0.
|
|||
# Quickstart
|
||||
|
||||
## Requirements
|
||||
- Neovim [nightly](https://github.com/neovim/neovim#install-from-source)
|
||||
- `git` in your path.
|
||||
- A C compiler in your path.
|
||||
|
||||
- Neovim [nightly](https://github.com/neovim/neovim#install-from-source)
|
||||
- `git` in your path.
|
||||
- A C compiler in your path.
|
||||
|
||||
## Installation
|
||||
|
||||
|
|
@ -24,6 +27,7 @@ You can install `nvim-treesitter` with your favorite package manager, or using t
|
|||
### Using a package manager
|
||||
|
||||
Simply add these lines to your `init.vim` :
|
||||
|
||||
```vim
|
||||
Plug 'nvim-treesitter/nvim-treesitter'
|
||||
```
|
||||
|
|
@ -31,6 +35,7 @@ Plug 'nvim-treesitter/nvim-treesitter'
|
|||
### Using neovim `pack` feature
|
||||
|
||||
We highly recommend reading `:h packages` to learn more about this feature, but you can still follow these steps:
|
||||
|
||||
```sh
|
||||
$ mkdir -p ~/.local/share/nvim/site/pack/nvim-treesitter/start
|
||||
$ cd ~/.local/share/nvim/site/pack/nvim-treesitter/start
|
||||
|
|
@ -45,6 +50,7 @@ provides two command to tackle this issue:
|
|||
- `TSInstallInfo` to know which parser is installed.
|
||||
|
||||
Let's say you need parsers for `lua`, `c`, and `python`, this is how you do with these commands:
|
||||
|
||||
```vim
|
||||
:TSInstall c
|
||||
Downloading...
|
||||
|
|
@ -63,6 +69,7 @@ Treesitter parser for python has been installed
|
|||
```
|
||||
|
||||
Cool, lets see which parsers are installed:
|
||||
|
||||
```vim
|
||||
:TSInstallInfo
|
||||
csharp [✗] not installed
|
||||
|
|
@ -91,27 +98,27 @@ And now you should be able to use every functionality `nvim-treesitter` provides
|
|||
|
||||
## Setup
|
||||
|
||||
in your `init.vim`:
|
||||
In your `init.vim`:
|
||||
|
||||
```lua
|
||||
lua <<EOF
|
||||
require'nvim-treesitter.configs'.setup {
|
||||
highlight = {
|
||||
enable = true, -- false will disable the whole extension
|
||||
disable = { 'c', 'rust' }, -- list of language that will be disabled
|
||||
custom_captures = { -- mapping of user defined captures to highlight groups
|
||||
-- ["foo.bar"] = "Identifier" -- highlight own capture @foo.bar with highlight group "Identifier", see :h nvim-treesitter-query-extensions
|
||||
},
|
||||
enable = true, -- false will disable the whole extension
|
||||
disable = { 'c', 'rust' }, -- list of language that will be disabled
|
||||
custom_captures = { -- mapping of user defined captures to highlight groups
|
||||
-- ["foo.bar"] = "Identifier" -- highlight own capture @foo.bar with highlight group "Identifier", see :h nvim-treesitter-query-extensions
|
||||
},
|
||||
},
|
||||
incremental_selection = {
|
||||
enable = true,
|
||||
disable = { 'cpp', 'lua' },
|
||||
keymaps = { -- mappings for incremental selection (visual mappings)
|
||||
init_selection = 'gnn', -- maps in normal mode to init the node/scope selection
|
||||
node_incremental = "grn", -- increment to the upper named parent
|
||||
scope_incremental = "grc", -- increment to the upper scope (as defined in locals.scm)
|
||||
node_decremental = "grm", -- decrement to the previous node
|
||||
}
|
||||
enable = true,
|
||||
disable = { 'cpp', 'lua' },
|
||||
keymaps = { -- mappings for incremental selection (visual mappings)
|
||||
init_selection = 'gnn', -- maps in normal mode to init the node/scope selection
|
||||
node_incremental = "grn", -- increment to the upper named parent
|
||||
scope_incremental = "grc", -- increment to the upper scope (as defined in locals.scm)
|
||||
node_decremental = "grm", -- decrement to the previous node
|
||||
}
|
||||
},
|
||||
refactor = {
|
||||
highlight_definitions = {
|
||||
|
|
@ -123,44 +130,44 @@ require'nvim-treesitter.configs'.setup {
|
|||
smart_rename = {
|
||||
enable = true,
|
||||
keymaps = {
|
||||
smart_rename = "grr" -- mapping to rename reference under cursor
|
||||
smart_rename = "grr" -- mapping to rename reference under cursor
|
||||
}
|
||||
},
|
||||
navigation = {
|
||||
enable = true,
|
||||
keymaps = {
|
||||
goto_definition = "gnd", -- mapping to go to definition of symbol under cursor
|
||||
list_definitions = "gnD" -- mapping to list all definitions in current file
|
||||
goto_definition = "gnd", -- mapping to go to definition of symbol under cursor
|
||||
list_definitions = "gnD" -- mapping to list all definitions in current file
|
||||
}
|
||||
}
|
||||
},
|
||||
textobjects = { -- syntax-aware textobjects
|
||||
enable = true,
|
||||
disable = {},
|
||||
keymaps = {
|
||||
["iL"] = { -- you can define your own textobjects directly here
|
||||
python = "(function_definition) @function",
|
||||
cpp = "(function_definition) @function",
|
||||
c = "(function_definition) @function",
|
||||
java = "(method_declaration) @function"
|
||||
},
|
||||
-- or you use the queries from supported languages with textobjects.scm
|
||||
["af"] = "@function.outer",
|
||||
["if"] = "@function.inner",
|
||||
["aC"] = "@class.outer",
|
||||
["iC"] = "@class.inner",
|
||||
["ac"] = "@conditional.outer",
|
||||
["ic"] = "@conditional.inner",
|
||||
["ae"] = "@block.outer",
|
||||
["ie"] = "@block.inner",
|
||||
["al"] = "@loop.outer",
|
||||
["il"] = "@loop.inner",
|
||||
["is"] = "@statement.inner",
|
||||
["as"] = "@statement.outer",
|
||||
["ad"] = "@comment.outer",
|
||||
["am"] = "@call.outer",
|
||||
["im"] = "@call.inner"
|
||||
}
|
||||
enable = true,
|
||||
disable = {},
|
||||
keymaps = {
|
||||
["iL"] = { -- you can define your own textobjects directly here
|
||||
python = "(function_definition) @function",
|
||||
cpp = "(function_definition) @function",
|
||||
c = "(function_definition) @function",
|
||||
java = "(method_declaration) @function"
|
||||
},
|
||||
-- or you use the queries from supported languages with textobjects.scm
|
||||
["af"] = "@function.outer",
|
||||
["if"] = "@function.inner",
|
||||
["aC"] = "@class.outer",
|
||||
["iC"] = "@class.inner",
|
||||
["ac"] = "@conditional.outer",
|
||||
["ic"] = "@conditional.inner",
|
||||
["ae"] = "@block.outer",
|
||||
["ie"] = "@block.inner",
|
||||
["al"] = "@loop.outer",
|
||||
["il"] = "@loop.inner",
|
||||
["is"] = "@statement.inner",
|
||||
["as"] = "@statement.outer",
|
||||
["ad"] = "@comment.outer",
|
||||
["am"] = "@call.outer",
|
||||
["im"] = "@call.inner"
|
||||
}
|
||||
},
|
||||
ensure_installed = 'all' -- one of 'all', 'language', or a list of languages
|
||||
}
|
||||
|
|
@ -170,6 +177,7 @@ EOF
|
|||
## Commands
|
||||
|
||||
Each feature can be enabled or disabled by different means:
|
||||
|
||||
```vim
|
||||
:TSBufEnable {module} " enable module on current buffer
|
||||
:TSBufDisable {module} " disable module on current buffer
|
||||
|
|
@ -182,11 +190,13 @@ Each feature can be enabled or disabled by different means:
|
|||
|
||||
The goal of `nvim-treesitter` is both to provide a simple and easy way to use the interface for Treesitter in Neovim,
|
||||
but also to add some functionalities to it:
|
||||
|
||||
Some of these features are :
|
||||
- [x] Incremental selection
|
||||
- [x] Syntax based code folding (`set foldmethod=expr foldexpr=nvim_treesitter#foldexpr()`)
|
||||
- [x] Consistent syntax highlighting (the api is not quite stable yet)
|
||||
- [x] Statusline indicator (`require'nvim-treesitter'.statusline(size)`)
|
||||
|
||||
- [x] Incremental selection
|
||||
- [x] Syntax based code folding (`set foldmethod=expr foldexpr=nvim_treesitter#foldexpr()`)
|
||||
- [x] Consistent syntax highlighting (the api is not quite stable yet)
|
||||
- [x] Statusline indicator (`require'nvim-treesitter'.statusline(size)`)
|
||||
|
||||
You can find the roadmap [here](https://github.com/nvim-treesitter/nvim-treesitter/projects/1).
|
||||
The roadmap and all features of this plugin are open to change, and any suggestion will be highly appreciated!
|
||||
|
|
@ -234,12 +244,13 @@ Modules can consist of the following properties:
|
|||
- `enable`: Determines if the module is enabled by default. This is usually overridden by the user.
|
||||
- `disable`: A list of languages that this module is disabled for. This is usually overridden by the user.
|
||||
- `is_supported`: A function that takes a language and determines if this module supports that language.
|
||||
- `attach`: A function that attachs to a buffer. This is required if `module_path` is not provided.
|
||||
- `attach`: A function that attaches to a buffer. This is required if `module_path` is not provided.
|
||||
- `detach`: A function that detaches from a buffer. This is required if `module_path` is not provided.
|
||||
|
||||
## Utils
|
||||
|
||||
you can get some utility functions with
|
||||
|
||||
```lua
|
||||
local ts_utils = require 'nvim-treesitter.ts_utils'
|
||||
```
|
||||
|
|
@ -294,9 +305,11 @@ For example, you can add files to `<vim-config-dir>/after/queries/lua/highlights
|
|||
You can also manually add query paths to the runtime path by adding this to your vim config `set rtp+='path/to/queries'`.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Before doing anything run `:checkhealth nvim_treesitter`. This will help you find where the bug might come from.
|
||||
|
||||
### Feature `X` does not work for language `Y`...
|
||||
|
||||
First, check the `## Y parser healthcheck` section of `:checkhealth` if you have any warning.
|
||||
If you do, it's highly possible that this is the cause of the problem.
|
||||
If everything is okay, then it might be an actual error.
|
||||
|
|
@ -307,7 +320,9 @@ In both cases, feel free to open an issue here.
|
|||
|
||||
This is a well known issue, which arise when the tree and the buffer are getting out of sync. \
|
||||
As this issue comes from upstream, we don't have any finite fix. To get around this, you can force reparsing the buffer with this command:
|
||||
|
||||
```vim
|
||||
:write | edit | TSBufEnable highlight
|
||||
```
|
||||
This will save, restore and enable highlighting for the current buffer, fixing the issue.
|
||||
|
||||
This will save, restore and enable highlighting for the current buffer, fixing the issue.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue