Skip to content
This repository was archived by the owner on Dec 4, 2025. It is now read-only.

Commit b24d43e

Browse files
Dwarf1erDwarf1er
authored andcommitted
docs: restructure README and add vim.pack configuration example
1 parent 1798c64 commit b24d43e

File tree

2 files changed

+436
-138
lines changed

2 files changed

+436
-138
lines changed

README.md

Lines changed: 105 additions & 138 deletions
Original file line numberDiff line numberDiff line change
@@ -13,88 +13,84 @@ auto-completion, go-to-definition, and more all from within Neovim 💻🔧
1313

1414
| Feature | Support |
1515
| --------------------- | ------- |
16-
| Hover ||
17-
| Diagnositcs ||
18-
| Go To Definition ||
19-
| Go To References ||
20-
| Semantic Highlighting ||
21-
| Formatting ||
22-
| Rename Symbol ||
23-
| Signature Help ||
24-
| Completions ||
25-
| Inlay Hints ||
26-
| Code Actions ||
27-
| Folding ||
28-
| CodeLens ||
29-
| Format New Files ||
16+
| Hover | |
17+
| Diagnostics | |
18+
| Go To Definition | |
19+
| Go To References | |
20+
| Semantic Highlighting | |
21+
| Formatting | |
22+
| Rename Symbol | |
23+
| Signature Help | |
24+
| Completions | |
25+
| Inlay Hints | |
26+
| Code Actions | |
27+
| Folding | |
28+
| CodeLens | |
29+
| Format New Files | |
3030

3131
> [!NOTE]
32-
> Semantic highlight groups need more configuration If you find a
33-
> property that isn't highlighted properly and is identified with `:Inspect`
34-
> please raise an issue, or a PR to link it to a highlight group.
35-
36-
## Installing the LSP
37-
38-
The LSP can be cloned and compiled from source from the `dotnet/razor` repo.
39-
40-
> [!TIP]
41-
> Alternatively, if you use `mason` to manage your LSP installs. A registry
42-
> containing both Roslyn and rzls is
43-
> configured [here](https://github.com/Crashdummyy/mason-registry)
44-
>
45-
> It can be included in your configuration like so:
46-
>
47-
> ```lua
48-
> require("mason").setup({
49-
> registries = {
50-
> "github:mason-org/mason-registry",
51-
> "github:Crashdummyy/mason-registry",
52-
> },
53-
> })
54-
> ```
55-
56-
## Configuration
57-
58-
You can pass a configuration table to the `setup` function. The configuration
59-
options are:
60-
61-
- `capabilities`: A table that defines the capabilities of the LSP client. If
62-
you don't know what this is, it can either be omitted or found in the
63-
documentation of your completion provider.
64-
- `path`: The path to the rzls executable if not installed via mason. If you
65-
have installed via mason you can omit this option.
66-
- `on_attach`: A function that is called when the LSP client attaches to a
67-
buffer. If you don't know what this is, or your on_attach function is provided
68-
by an autocommand, omit the option, or pass an empty function.
32+
> Semantic highlight groups may need extra configuration.
33+
> If `:Inspect` shows a token that's not highlighted correctly, please open an issue or PR to map it to an appropriate highlight group.
34+
35+
## Table of Contents
36+
- [rzls.nvim 🚀](#rzlsnvim-)
37+
- [Description 📄](#description-)
38+
- [Features](#features)
39+
- [Table of Contents](#table-of-contents)
40+
- [Dependencies](#dependencies)
41+
- [Installing `rzls.nvim`](#installing-rzlsnvim)
42+
- [lazy.nvim](#lazynvim)
43+
- [vim.pack (Neovim v0.12+)](#vimpack-neovim-v012)
44+
- [Plugin Configuration](#plugin-configuration)
45+
- [Configuring `seblyng/roslyn.nvim`](#configuring-seblyngroslynnvim)
46+
- [Manually](#manually)
47+
- [Mason](#mason)
48+
- [Configuring `rzls.nvim`](#configuring-rzlsnvim)
49+
- [Additional Configuration](#additional-configuration)
50+
- [Telescope.nvim](#telescopenvim)
51+
- [Trouble.nvim](#troublenvim)
52+
- [Example Configuration](#example-configuration)
53+
- [Known Issues](#known-issues)
54+
- [Contributing](#contributing)
55+
- [Helping Out](#helping-out)
56+
- [License](#license)
6957

7058
## Dependencies
7159

72-
You must install the following plug-ins:
73-
74-
- [`seblyng/roslyn.nvim`](https://github.com/seblyng/roslyn.nvim) for general
75-
functionality
76-
- `html-lsp` for completions and formatting. You can install and configure it
77-
via `mason` and `nvim-lspconfig`.
60+
- [`roslyn`](https://github.com/crashdummyy/roslynlanguageserver) - The C# language server. Required for all C# and Razor/Blazor integrations.<br/>
61+
- [`rzls`](https://github.com/crashdummyy/rzls) - The Razor language server. Handles Razor/Blazor/CSHTML integrations.<br/>
62+
- [`html-lsp`](https://github.com/microsoft/vscode-html-languageservice) - The HTML language server. Provides completions and formatting for HTML inside `.razor` files.<br/>
63+
- [`seblyng/roslyn.nvim`](https://github.com/seblyng/roslyn.nvim) - Neovim integration for `roslyn`. Handles communication between Neovim and the `roslyn` language server.<br/>
7864

7965
> [!CAUTION]
80-
> Please see the Integration section for extra arguments that must be passed to
66+
> Please see the [configuring seblyng/roslyn.nvim](#configuring-seblyngroslynnvim) section for extra arguments that must be passed to
8167
> `roslyn.nvim` setup.
8268
83-
## Integration
69+
## Installing `rzls.nvim`
70+
71+
### lazy.nvim
72+
73+
```lua
74+
return {
75+
"tris203/rzls.nvim"
76+
}
77+
```
78+
79+
### vim.pack (Neovim v0.12+)
80+
81+
```lua
82+
vim.pack.add({ "https://github.com/tris203/rzls.nvim.git" })
83+
```
8484

85-
You also must configure the
86-
[`roslyn.nvim`](https://github.com/seblyng/roslyn.nvim) plugin to communicate
87-
with the rzls. To do so, you must pass the handlers defined in the
88-
`rzls.roslyn_handlers` module and adjust the CLI command that Roslyn uses.
85+
## Plugin Configuration
8986

90-
### Composing the command for Roslyn
87+
### Configuring `seblyng/roslyn.nvim`
9188

92-
To configure `roslyn.nvim`, you need to compose a shell command string with
93-
arguments for it. Some of these arguments are CLI-options relating to rzls. You
94-
can compose the command as follows, depending on whether you installed Roslyn
95-
and rzls manually or with mason.
89+
To ensure seamless communication between `roslyn.nvim` and `rzls`, you need to configure `roslyn.nvim` with specific command-line arguments and handlers provided by `rzls.nvim`. This involves composing the `roslyn` language server command with arguments that point to the installed `rzls`. You’ll also need to pass the handler functions defined in the `rzls.roslyn_handlers` module to `roslyn.nvim`'s setup.
9690

97-
Manually:
91+
Below are examples showing how to assemble the `cmd` for both manual and Mason installations, followed by how to use this command in your `roslyn.nvim` `setup()`.
92+
93+
#### Manually
9894

9995
```lua
10096
-- Adjust these paths to where you installed Roslyn and rzls.
@@ -108,17 +104,18 @@ local cmd = {
108104
"--logLevel=Information",
109105
"--extensionLogDirectory=" .. vim.fs.dirname(vim.lsp.get_log_path()),
110106
"--razorSourceGenerator=" .. vim.fs.joinpath(rzls_base_path, "Microsoft.CodeAnalysis.Razor.Compiler.dll"),
111-
"--razorDesignTimePath="
112-
.. vim.fs.joinpath(rzls_base_path, "Targets", "Microsoft.NET.Sdk.Razor.DesignTime.targets"),
107+
"--razorDesignTimePath=" .. vim.fs.joinpath(rzls_base_path, "Targets", "Microsoft.NET.Sdk.Razor.DesignTime.targets"),
108+
"--extension",
109+
vim.fs.joinpath(rzls_base_path, "RazorExtension", "Microsoft.VisualStudioCode.RazorExtension.dll"),
113110
}
114111
```
115112

116-
With mason:
113+
#### Mason
117114

118115
```lua
119-
local mason_registry = require("mason-registry")
120-
116+
require("mason-registry")
121117
local rzls_path = vim.fn.expand("$MASON/packages/rzls/libexec")
118+
122119
local cmd = {
123120
"roslyn",
124121
"--stdio",
@@ -131,74 +128,37 @@ local cmd = {
131128
}
132129
```
133130

134-
Finally, use the composed `cmd` and rzls handlers like so:
135-
131+
Finally, regardless of which method you used to compose the `cmd` table, use it together with `rzls.roslyn_handlers` in your `roslyn.nvim` setup like so:
136132
```lua
137133
require("roslyn").setup({
138134
cmd = cmd,
139135
config = {
140-
-- the rest of your Roslyn configuration
136+
-- The rest of your Roslyn configuration
141137
handlers = require("rzls.roslyn_handlers"),
142138
},
143139
})
144140
```
145141

146-
## Example configuration
142+
### Configuring `rzls.nvim`
143+
144+
You can customize `rzls.nvim` by passing a configuration table to its `setup` function. Here are the options:
145+
146+
- **`capabilities`**
147+
A table describing what features your LSP client supports (like completion, hover, etc.).
148+
If you're using a completion plugin (like `nvim-cmp`), you can pass its capabilities here.
149+
If you're unsure, you can leave this out or consult the documentation of your completion provider.
150+
151+
- **`path`**
152+
The file system path to the `rzls` executable.
153+
If you installed `rzls` via Mason, you don't need to set this.
154+
But if you installed it manually, set this to the full path to your `rzls` binary.
155+
156+
- **`on_attach`**
157+
A function called when the language server attaches to a buffer, often used to set up keymaps or other buffer-local settings.
158+
If you already manage `on_attach` globally (e.g., via autocommands), you can omit this or provide an empty function.
147159

148160
```lua
149-
return {
150-
{
151-
"seblyng/roslyn.nvim",
152-
ft = { "cs", "razor" },
153-
dependencies = {
154-
{
155-
-- By loading as a dependencies, we ensure that we are available to set
156-
-- the handlers for Roslyn.
157-
"tris203/rzls.nvim",
158-
config = true,
159-
},
160-
},
161-
config = function()
162-
-- Use one of the methods in the Integration section to compose the command.
163-
local cmd = {}
164-
165-
vim.lsp.config("roslyn", {
166-
cmd = cmd,
167-
handlers = require("rzls.roslyn_handlers"),
168-
settings = {
169-
["csharp|inlay_hints"] = {
170-
csharp_enable_inlay_hints_for_implicit_object_creation = true,
171-
csharp_enable_inlay_hints_for_implicit_variable_types = true,
172-
173-
csharp_enable_inlay_hints_for_lambda_parameter_types = true,
174-
csharp_enable_inlay_hints_for_types = true,
175-
dotnet_enable_inlay_hints_for_indexer_parameters = true,
176-
dotnet_enable_inlay_hints_for_literal_parameters = true,
177-
dotnet_enable_inlay_hints_for_object_creation_parameters = true,
178-
dotnet_enable_inlay_hints_for_other_parameters = true,
179-
dotnet_enable_inlay_hints_for_parameters = true,
180-
dotnet_suppress_inlay_hints_for_parameters_that_differ_only_by_suffix = true,
181-
dotnet_suppress_inlay_hints_for_parameters_that_match_argument_name = true,
182-
dotnet_suppress_inlay_hints_for_parameters_that_match_method_intent = true,
183-
},
184-
["csharp|code_lens"] = {
185-
dotnet_enable_references_code_lens = true,
186-
},
187-
},
188-
})
189-
vim.lsp.enable("roslyn")
190-
end,
191-
init = function()
192-
-- We add the Razor file types before the plugin loads.
193-
vim.filetype.add({
194-
extension = {
195-
razor = "razor",
196-
cshtml = "razor",
197-
},
198-
})
199-
end,
200-
},
201-
}
161+
require("rzls").setup({})
202162
```
203163

204164
## Additional Configuration
@@ -212,7 +172,7 @@ to exclude references in the generated virtual files.
212172
```lua
213173
require("telescope").setup({
214174
defaults = {
215-
file_ignore_patterns = { "%__virtual.cs$" },
175+
file_ignore_patterns = { "__virtual%.cs$" },
216176
},
217177
})
218178
```
@@ -228,29 +188,32 @@ require("trouble").setup({
228188
diagnostics = {
229189
filter = function(items)
230190
return vim.tbl_filter(function(item)
231-
return not string.match(item.basename, [[%__virtual.cs$]])
191+
return not string.match(item.basename, [[__virtual%.cs$]])
232192
end, items)
233193
end,
234194
},
235195
},
236196
})
237197
```
238198

199+
## Example Configuration
200+
201+
For detailed setup, see the [configuration examples](./doc/CONFIGURATION.md).
202+
239203
## Known Issues
240204

241205
- Native Windows support doesn't work at this time, due to path normalization.
242-
- Opening a CS file first means that Roslyn and rzls don't connect properly.
206+
- Opening a CS file first means that `roslyn` and `rzls` don't connect properly.
243207

244208
## Contributing
245209

246-
This plugin is still under construction. The Razor Language Server (rzls) uses a
247-
variety of custom methods that need to be understood and implemented. We are
210+
This plugin is still under construction. The Razor Language Server (`rzls`) uses
211+
several custom methods that need to be understood and implemented. We are
248212
actively working on this and appreciate your patience.
249213

250214
We welcome contributions from the community for support of new features, fixing
251215
bugs, issues or things on the TODO-list (Grep the code for `TODO`). If you have
252-
experience with LSP or
253-
Razor and would like to contribute, please open a Pull Request. If
216+
experience with LSP or Razor and would like to contribute, please open a Pull Request. If
254217
you encounter any issues or have suggestions for improvements, please open an
255218
Issue. Your input is valuable in making this plugin more robust and efficient.
256219

@@ -261,3 +224,7 @@ anything you would like to discuss, or you want to help. Come say hi.
261224

262225
If you want to help out, then please see the discussion here, and leave a
263226
comment with your details in this [discussion](https://github.com/tris203/rzls.nvim/discussions/1).
227+
228+
## License
229+
230+
This project is licensed under the [MIT license](LICENSE).

0 commit comments

Comments
 (0)