feat: add docs for neovim setup #3322

jpoly1219 · 2025-09-19T07:46:36Z

Closes #3319 .

Added docs for setting up the LSP server on Neovim.

Add docs for using nvim-lspconfig and vim.lsp. Both methods are frequently used, and it's a good idea to add instructions for nvim-lspconfig because vim.lsp only supports Neovim versions 0.11 and above.

syaiful6 · 2025-09-19T08:22:14Z

data/tutorials/getting-started/2_00_editor_setup.md

+  -- other packages...
+  {
+    'neovim/nvim-lspconfig',
+    config = function()


here, I think we need to set mason = false. Otherwise it will not work, at least this is how experienced in the past.

Oh interesting, my current configuration uses Mason alongside ocamllsp. I don't think I've ran into issues compared yet.

yeah, this is probably because ocamllsp is version sensitive as you mentioned, probably at that time the version installed in mason not compatible. So, I decided to install ocaml-lsp-server for each project.

anyway, I think this is look good to me.

Isn't that option related to LazyVim and not lazy.nvim?

boltlessengineer

Do we really need to explain about lazy.nvim and neovim/nvim-lspconfig here? They aren't really a dependency for proper setup so they should be at least less preferred here.

I know many people are still using them, but I think they might introduce too much complexity considering the purpose of this document.

nvim-lspconfig is already using vim.lsp internally afaik so I think just directly showing vim.lsp based config here can actually be enough.

We can let users switch to nvim-lspconfig for even shorter one-liner setup if they have an existing neovim config with lspconfig.

-- this should be enough for them. Others are just boilerplates.
require('lspconfig').ocamllsp.setup()

boltlessengineer · 2025-09-19T12:53:00Z

data/tutorials/getting-started/2_00_editor_setup.md

+```lua
+-- path/to/config/lua/lsp/servers.lua
+vim.lsp.config['ocamllsp'] = {
+  cmd = { 'ocamllsp' },
+  filetypes = { 'ocaml', 'ocaml.interface', 'ocaml.menhir', 'reason' },
+  root_markers = { { 'dune-project', 'dune-workspace' }, '.git' },
+  settings = {},
+}


I think it would be more idiomatic in Neovim to put lsp server config under lsp/ocamllsp.lua rather than lua/lsp/*.lua.

Now even less code and they are in right place rather than imported manually.

:h 'runtimepath'

-- path/to/config/lsp/ocamllsp.lua return { cmd = { 'ocamllsp' }, filetypes = { 'ocaml', 'ocaml.interface', 'ocaml.menhir', 'reason' }, root_markers = { { 'dune-project', 'dune-workspace' }, '.git' }, settings = {}, } -- init.lua vim.lsp.enable('ocamllsp')

jpoly1219 · 2025-09-19T16:18:30Z

@boltlessengineer Thank you for the review! I made the necessary changes. Let me know if you'd prefer to see an even shorter version.

Your point makes a lot of sense in that we shouldn't cover the full setup of package managers and setup, because that's out of scope of this guide. And I like your comment on the vim.lsp changes.

I think the notion of adding boilerplate was to give more context to the users, as I used to struggle a lot with terse setup documentation. Call it skill issue but I would've appreciated having a minimal boilerplate in a setup guide, as it's a lot easier to make sense of where to actually put the config😅 I'd rather not assume that all Neovim users are wizards who know the full ins and outs of their config.

boltlessengineer

While I appreciate the change on nvim-lspconfig section, the vim.lsp section... got worse. I should have explained it more clearly.

There are so many ways to configure a LSP with vim.lsp.

base configuration defined for the * name
configuration defined in <rtp>/lsp/<name>.lua
configuration defined by vim.lsp.config() in anywhere else

We cannot explain all of these.

So I think separating explanations of configuration and activation(enabling) can be clear enough.

explain that you should 1) configure and 2) enable the language server.
show the single init.lua example as that is best for copy-pasting
show that you can put configuration table under <rtp>/lsp/<name>.lua.
NOTE: this is not a lua module!! it's a rtp file
link to :h lsp-config so that users can learn about this from official document.
put common lazy.nvim way to do this

Or remove the part 2 and only show runtimepath (lsp/ folder) way. Because that's also what nvim-lspconfig is using internally.

So:

... explain that you should configure and enable the server.

Using vim.lsp:

See :h lsp-config for detailed information.

-- in your `init.lua` file

-- configure ocamllsp
vim.lsp.config('ocamllsp', {
  -- ...
})

-- enable ocamllsp
vim.lsp.enable('ocamllsp')

placing ocamllsp configuration in separate file

Instead of calling vim.lsp.config, you can put ocamllsp configuration table in separate file. Neovim will automatically search for lsp/<name>.lua or after/lsp/<name>.lua files and merge them all in single config. (see :h lsp-config and :h 'runtimepath')

-- in `lsp/ocamllsp.lua` (not `lua/lsp/ocamllsp.lua`)
return {
  -- ...
}

Now you can enable ocamllsp from your init.lua

vim.lsp.enable('ocamllsp')

... show lazy.nvim and nvim-lspconfig way

boltlessengineer · 2025-09-20T04:48:05Z

data/tutorials/getting-started/2_00_editor_setup.md

+You can also use `vim.lsp` with a modular config.
+
+Assume that your config has the following structure. The internal structure of `lua` does not matter much.
+```text
+.
+├── init.lua
+└── lua
+    ├── custom
+    │   └── plugins
+    │       └── some-plugin.lua
+    └── kickstart
+        ├── health.lua
+        └── plugins
+            └── some-plugin.lua
+```
+
+Then run the following at the root of your config.
+```text
+mkdir lsp
+touch lsp/ocamllsp.lua
+```
+
+We now add our LSP configs to `lsp/ocamllsp.lua`...
+```lua
+return {
+  cmd = { 'ocamllsp' },
+  filetypes = { 'ocaml', 'ocaml.interface', 'ocaml.menhir', 'reason' },
+  root_markers = { { 'dune-project', 'dune-workspace' }, '.git' },
+  settings = {},
+}
+```
+
+...and import them in the toplevel `init.lua`.


You are missunderstanding lsp/ folder.
It's a runtimepath file. Read automatically by Neovim on startup. It's not a lua module.

When calling vim.lsp.enable, we aren't importing it. We've already done configuring by placing the lsp config table in <rtp>/lua/<name>.lua files or by calling/setting vim.lsp.config directly.

@boltlessengineer this correct, my understanding is he mean to create lsp/ folder in root config. It will get installed to ~/.config/nvim/lsp/ocamllsp.lua.

@boltlessengineer should've been more pedantic about the wording here, mb. What I meant by import was to call require.

I don't think I said to add the lsp configs to lua? But I can see how giving more context on the config folder structure can be potentially misleading.

I'm saying that we aren't requiring lsp/ocamllsp.lua by calling vim.lsp.enable().
vim.lsp.config and vim.lsp.enable are completely different things.

Both term 'import' and 'require' doesn't fit here.

What vim.lsp.enable is doing is just: Setup that language server with configured value which is pre-merged vim.lsp.config table. It isn't about loading & merging configs, but about setting up a required autocmds. (to auto-start language server on filetypes)

When someone wants to configure a server, defining a table in <rtp>/lsp/<name>.lua is just enough. It will be auto-merged whenever you indexed the vim.lsp.config like vim.lsp.config['ocamllsp']

check this out:

write lsp/ocamllsp.lua and do nothing else, don't enable it yet

open neovim and run `:=vim.lsp.config['ocamllsp']

see it already contains the merged config.

data/tutorials/getting-started/2_00_editor_setup.md

+    -- rest of config...
+
+    -- add this line specifically for OCaml
+    require('lspconfig').ocamllsp.setup {}


jpoly1219 · 2025-09-20T05:54:35Z

@boltlessengineer made more edits, lmk if it looks better.

boltlessengineer

Except for some nits on wording, all seems good now!

I'm curious if mentioning vim.lsp.start can help here. Do you think it can help? or is it too much?

boltlessengineer · 2025-09-20T06:00:54Z

data/tutorials/getting-started/2_00_editor_setup.md

+#### Modular Config With Runtimepath
+
+You can also use `vim.lsp` with a modular config via `runtimepath`. Putting your config table inside `lsp/<some_name>.lua` or `after/lsp/<some_name>.lua` will allow Neovim to search for them automatically.
+
+See `:h runtimepath` for more detail.


The term "modular" might confuse users with typical lua modules. They aren't. Lua modules in Neovim config only lives in lua/ directory and lsp/*.lua are just plain standalone lua files loaded by neovim directly.

I think "multi-file" can be better for clarity.

I'm not sure if that distinction is strictly necessary 🤔 I think most people understand what a modular config means in general and are more familiar with that term. I've seen lots of modular config out there but not a single multi-file config.

People don't use runtimepath much for lsp/general config because of historical reasons.
But now they are available and is completely different thing from structuring everything under lua/ directory.

Even though we clearly stated that they should put that file under lsp/ and not lua/lsp/, I think calling it as a "module" or saying this structure "modular" might confuse users between runtimepath and lua-modules.

@boltlessengineer I'll make the changes and request for another review 👍

boltlessengineer · 2025-09-20T06:07:40Z

data/tutorials/getting-started/2_00_editor_setup.md

 ```

-...and import them in the toplevel `init.lua`.
+Then enable them in the toplevel `init.lua`.


another nit: Can we explain what vim.lsp.enable() do here? It will help users understand the difference between configuration and enabling.

Then enable them in the toplevel init.lua. This will make Neovim to automatically start the ocamllsp for associated filetypes.
..codeblock..
To start ocamllsp manually, you can use vim.lsp.start. (see :h vim.lsp.start)

:lua vim.lsp.start(vim.lsp.config['ocamllsp'])

Not sure if we want to mention vim.lsp.start here. I think it can help users to understand what vim.lsp.enable actually does, but it can be yet another code snippet they should read and understand.

I feel like this is a bit out of scope for the purpose of this doc. I think the curious readers will go out and research this further on their own.

Maybe instead of calling lsp.enable with just ocamllsp we could show that you only need to call this once, with a list of languages (OCaml being just one of them), but it is fine as it is too.
Maybe add a link to the official NeoVim LSP docs? https://neovim.io/doc/user/lsp.html

We are already mentioning it. :h lsp-config should be enough.

boltlessengineer

LGTM!

edwintorok · 2025-09-20T19:23:23Z

data/tutorials/getting-started/2_00_editor_setup.md

+```lua
+vim.lsp.config['ocamllsp'] = {
+  cmd = { 'ocamllsp' },
+  filetypes = { 'ocaml', 'ocaml.interface', 'ocaml.menhir', 'reason' },


ocamllsp.lua from nvim-lspconfig also adds ocaml.ocamllex, and dune to this list, but it does it in an awkward way, the filetype is actually called ocamlinterface and it gets mapped to ocaml.interface using get_language_id.

edwintorok · 2025-09-20T19:24:00Z

data/tutorials/getting-started/2_00_editor_setup.md

+```lua
+return {
+  cmd = { 'ocamllsp' },
+  filetypes = { 'ocaml', 'ocaml.interface', 'ocaml.menhir', 'reason' },


same as above, this filetype list could probably be longer

edwintorok · 2025-09-20T19:29:30Z

data/tutorials/getting-started/2_00_editor_setup.md

+```
+
+There is no need to pass more settings to `setup` because `nvim-lspconfig` provides reasonable defaults. See [here](https://github.com/neovim/nvim-lspconfig/blob/master/lsp/ocamllsp.lua) for more info.
+


Should we explain about tree-sitter? (with nvim-treesitter)?

local treesitter_langs = { 'menhir', 'ocaml', 'ocaml_interface', 'ocamllex' } require('nvim-treesitter').install(treesitter_langs)

It isn't strictly required, although might help with performance on large files, before the LSP finishes parsing it.
Maybe leave it out for now, I'll do some experiments with using just the LSP, and see how well that works.

Sounds good. Let me know if you have more updates 👍

I figured out how to configure tree-sitter for ocamllex, but it is quite complicated: ocaml/vim-ocaml#61 (comment).

For now I'd leave out tree-sitter from the official docs, until that PR is merged (and an equivalent PR is merged into NeoVim).

The workaround is (fixes both picking the right tree-sitter syntax and the LSP errors):

vim.filetype.add({ extension = { mll = 'ocamllex', mly = 'menhir', mli = 'ocamlinterface' } })

followed by the usual tree-sitter config:

local treesitter_langs = { 'menhir', 'ocaml', 'ocaml_interface', 'ocamllex' } require('nvim-treesitter').install(treesitter_langs)

(This doesn't require a new release of NeoVim to work, but if your tree-sitter grammar fails to install you'll be without syntax highlighting, so I wouldn't propose it in the official docs, even though I'll start using it myself).

edwintorok

Thanks, this is a good start!

We can perhaps have a separate section that shows the more advanced features (inlay hints, etc.), I can try to prepare a separate PR about that.

jpoly1219 · 2025-09-20T19:56:27Z

@edwintorok I went ahead and added more filetypes and root path. Could you take another quick look at it please?

I'll leave the settings field empty until you play around with more advanced lsp/merlin features.

edwintorok · 2025-09-20T20:14:31Z

data/tutorials/getting-started/2_00_editor_setup.md

+    'ocaml',
+    'ocaml.interface',
+    'ocaml.menhir',
+    'ocaml.ocamllex',


This one doesn't actually seem to work on NeoVim 0.11.4 and ocamllsp 1.23.0.
ocamllsp says 'unsupported file extension'.
But removing it from this list doesn't work either, because then it falls back to the ocaml filetype on the .mll file, and calls ocamllsp anyway.

The rest seems to work.

Ah ocaml.ocamllex is to future-proof it for ocaml/vim-ocaml#61 (which isn't merged yet)

#3322 (comment) workaround, but ocaml.ocamllex is fine as it is in the suggested doc, even though it doesn't work yet.

edwintorok · 2025-09-24T20:36:03Z

data/tutorials/getting-started/2_00_editor_setup.md

+    'dune',
+    'reason'
+  },
+  root_markers = {


Nice!

I proposed this simplification to the upstream nvim-lspconfig, which was using a root_dir function and lspconfig.util instead (which appears deprecated).

sabine

Hey, thanks for adding this @jpoly1219 and thanks for reviewing @edwintorok, @boltlessengineer, @syaiful6!

Since I haven't used neovim, I can't say anything about the instructions, but it's great to have something to help guide new OCaml users on neovim now!

jpoly1219 · 2025-10-07T16:01:49Z

@sabine glad I could help :)

feat: add docs for neovim setup

af40ef5

syaiful6 reviewed Sep 19, 2025

View reviewed changes

boltlessengineer suggested changes Sep 19, 2025

View reviewed changes

fix: trim docs

be18a82

jpoly1219 requested review from boltlessengineer and syaiful6 September 19, 2025 16:19

syaiful6 approved these changes Sep 20, 2025

View reviewed changes

boltlessengineer suggested changes Sep 20, 2025

View reviewed changes

fix: wording

2101553

jpoly1219 requested a review from boltlessengineer September 20, 2025 05:54

boltlessengineer suggested changes Sep 20, 2025

View reviewed changes

fix: reword modular

d2f6eee

jpoly1219 requested a review from boltlessengineer September 20, 2025 06:34

boltlessengineer approved these changes Sep 20, 2025

View reviewed changes

edwintorok reviewed Sep 20, 2025

View reviewed changes

fix: add more filetypes and root paths

58a5b90

jpoly1219 requested a review from edwintorok September 20, 2025 19:56

edwintorok reviewed Sep 20, 2025

View reviewed changes

edwintorok approved these changes Sep 20, 2025

View reviewed changes

edwintorok mentioned this pull request Sep 20, 2025

Avoid NeoVim error when opening .mll files ocaml/ocaml-lsp#1557

Merged

edwintorok reviewed Sep 24, 2025

View reviewed changes

sabine approved these changes Oct 2, 2025

View reviewed changes

sabine merged commit 4a69657 into ocaml:main Oct 2, 2025
3 of 4 checks passed

		```

		There is no need to pass more settings to `setup` because `nvim-lspconfig` provides reasonable defaults. See [here](https://github.com/neovim/nvim-lspconfig/blob/master/lsp/ocamllsp.lua) for more info.

feat: add docs for neovim setup #3322

feat: add docs for neovim setup #3322

Conversation

jpoly1219 commented Sep 19, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

boltlessengineer left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jpoly1219 commented Sep 19, 2025

Uh oh!

boltlessengineer left a comment

Choose a reason for hiding this comment

Using vim.lsp:

placing ocamllsp configuration in separate file

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as resolved.

Uh oh!

jpoly1219 commented Sep 20, 2025

Uh oh!

boltlessengineer left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

boltlessengineer Sep 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jpoly1219 Sep 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

boltlessengineer left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

edwintorok Sep 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

edwintorok left a comment

Choose a reason for hiding this comment

Uh oh!

boltlessengineer Sep 20, 2025 •

edited

Loading

jpoly1219 Sep 20, 2025 •

edited

Loading

edwintorok Sep 20, 2025 •

edited

Loading

jpoly1219 commented Sep 20, 2025 •

edited

Loading

edwintorok Sep 20, 2025 •

edited

Loading