Skip to content

feat: add docs for neovim setup #3322

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sabine merged 5 commits into from
Oct 2, 2025
Merged

feat: add docs for neovim setup #3322

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
af40ef5
feat: add docs for neovim setup
jpoly1219 Sep 19, 2025
be18a82
fix: trim docs
jpoly1219 Sep 19, 2025
2101553
fix: wording
jpoly1219 Sep 20, 2025
d2f6eee
fix: reword modular
jpoly1219 Sep 20, 2025
58a5b90
fix: add more filetypes and root paths
jpoly1219 Sep 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 85 additions & 0 deletions data/tutorials/getting-started/2_00_editor_setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -145,3 +145,88 @@ opam user-setup install
- Type `:MerlinTypeOf` and press <kbd>Enter</kbd>.
- The type information will be displayed in the command bar.
Other Merlin commands for Vim are available and you can checkout their usage on the [Merlin official documentation for Vim](https://ocaml.github.io/merlin/editor/vim/).

## Neovim

Neovim comes with an LSP client.

One note here is that is that `ocaml-lsp-server` is sensitive to versioning, and often does not play well with the sometimes outdated sources in Mason, a popular package manager for language services. We recommend you install the LSP server directly in the switch, and pointing your Neovim config to use that.

To install the LSP server and the formatter, run the following.
```shell
opam install ocaml-lsp-server ocamlformat
```

There are two main ways to install and manage LSP servers.
- A newer, more recommended way is to use the new Neovim LSP API for versions newer than v0.11.0 via `vim.lsp`.
- A more traditional way is to use `nvim-lspconfig`. For more info, `kickstart.nvim` has a great example setup.

### Using vim.lsp:

Add this to your toplevel `init.lua`.
```lua
vim.lsp.config['ocamllsp'] = {
cmd = { 'ocamllsp' },
filetypes = { 'ocaml', 'ocaml.interface', 'ocaml.menhir', 'reason' },
Copy link
Contributor

@edwintorok edwintorok Sep 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

root_markers = { { 'dune-project', 'dune-workspace' }, '.git' },
settings = {},
}

vim.lsp.enable 'ocamllsp'
```

See `:h lsp-config` for more detail on configuration options.

#### 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.
Copy link

@boltlessengineer boltlessengineer Sep 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@jpoly1219 jpoly1219 Sep 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link

@boltlessengineer boltlessengineer Sep 20, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@jpoly1219 jpoly1219 Sep 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


Run the following at the root of your config.
```text
mkdir lsp
touch lsp/ocamllsp.lua
```

Your Neovim config should have the following structure now.
```text
.
├── init.lua
├── lsp
│ └── ocamllsp.lua
└── ...
```

Add your LSP config to `lsp/ocamllsp.lua`.
```lua
return {
cmd = { 'ocamllsp' },
filetypes = { 'ocaml', 'ocaml.interface', 'ocaml.menhir', 'reason' },
Copy link
Contributor

@edwintorok edwintorok Sep 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same as above, this filetype list could probably be longer

root_markers = { { 'dune-project', 'dune-workspace' }, '.git' },
settings = {},
}
```

Then enable them in the toplevel `init.lua`.
Copy link

@boltlessengineer boltlessengineer Sep 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@jpoly1219 jpoly1219 Sep 20, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

@edwintorok edwintorok Sep 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link

@boltlessengineer boltlessengineer Sep 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

```lua
vim.lsp.enable 'ocamllsp'
```

### Using nvim-lspconfig

Add this to your `nvim-lspconfig` setup.
```lua
{
'neovim/nvim-lspconfig',
config = function()
-- rest of config...

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

This comment was marked as resolved.

Sign in to view

end,
},
```

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.

Copy link
Contributor

@edwintorok edwintorok Sep 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@jpoly1219 jpoly1219 Sep 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

@edwintorok edwintorok Sep 20, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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