Tutorial request megathread

Hi all,

To bootstrap the discourse, I want to start generating (and soliciting) high quality content. I’ll try to post something once a week.

Here are some ideas:

  1. Interactive lua debugging and developing with nvim-luadev
  2. A crash course on GDB, address santization (ASAN), memory leaks, and debugging neovim
  3. Naming conventions and organization of the core C components of neovim
  4. Writing user interfaces in neovim (neovim-ui development)
  5. Extending the language server client in neovim
  6. Writing new syntax rules for neovim
  7. Writing a GUI for neovim (zig?)
  8. Using debug adapter protocol via nvim-dap
  9. Using libuv for async, await, coroutines, parallelism, etc.
  10. Developing a lua plugin

Please post your requests and ideas!


Maybe this is a different kind of tutorial, but I’d love to see a screencast on setting up DAP in a non-trivial software project. mfussenegger seems to be doing a heroic job of developing Nvim-DAP without much fanfare, but I’m having a hard time getting it to all work right even after reading the docs, skimming parts of the source code, and even getting 1:1 help from mfussenegger in IRC. I think I just need to see a working usage example in a nontrivial code base.


For naming conventions/style, note that there is a guide for that, which should be at least somewhat relevant (learned it existed after some discussion on Gitter). Might be a good idea to go through that at some point though and see if anything needs updating.

There’s also this write-up from a few years ago about Neovim’s architecture which may be useful for those interested: Neovim · Delft Students on Software Architecture: DESOSA 2017. Not sure how much has changed since that was written, but I’d guess it’s still helpful and (at least mostly?) accurate.

1 Like

Yes, there are already some great resources on some of these topics. For async/await there is GitHub - ms-jpq/neovim-async-tutorial: Async Await in 90 lines of code.

Something that I’d find useful is a guide implementing new options and commands; almost any new feature will need to do this. What are the types of options, what do you need to watch out for, examples, etc.

What do you mean “options and commands”? Like how to map a vim command in your plugin?

Defining new options (:set <name>=) in options.lua, and commands such as :terminal or :edit

A crash course on GDB

Does this include a simple TUI / key shortcut setup for gdb or llvm? Ideally 1+8 can be combined to have some more consistent keymappings.

  1. Writing new syntax rules for neovim

vimscript syntax files or treesitter grammar? I found the syntax files fairly simple to handle, but the available color groups (for different languages etc) quite overwhelming.

  1. Writing a GUI for neovim (zig?)

What should the purpose of the GUI be?
Aside: river should give some inspiration. They plan a keymap protocol and do interesting stuff like dynamic tiling. Demonstration at around 46:00. I am fairly confident they will offer tmux-like workflows, so integration should be very interesting. Once they release.

Does this include a simple TUI / key shortcut setup for gdb or llvm? Ideally 1+8 can be combined to have some more consistent keymappings.

I can include some of this in the nvim-dbg tutorial. I personally use gdb from the command line using gdb-server when I’m trying to debug an issue in core.

vimscript syntax files or treesitter grammar? I found the syntax files fairly simple to handle, but the available color groups (for different languages etc) quite overwhelming.

Mostly I was planning on double dipping, as I’m writing custom syntax rules to deal with rendering of markdown escaped characters for LSP, but I can do a separate tutorial on tree-sitter grammars.

What should the purpose of the GUI be?

The purpose is mostly didactic, @smolck and I were talking about this on matrix, and @bfredl has given me a strong interest in trying out zig for a larger project.

If we are creating a megathread here, I think it would be nice to pull together some of the resources that are scattered into a more refined compilation. Personally, I would love to start learning how to make plugins with Lua and Neovim nightly but am not entirely sure what resources (tutorials) out there are quality and reliable.

So I did compile this: About the Lua category

Maybe we can add a sidebar or something, or maybe that should also be in the plugins group. We’re still solidifying the categories and trying to make things discoverable.

ah I did not see that! Thank for linking it! I will have to check out the resources linked there.

I’ve been using the built-in Termdebug plugin to try and debug some issues with Neovim and I find it to be a really nice wrapper around gdb. It might be a good idea to mention it in the gdb tutorial

Maybe something about code navigation would be interesting? I often use the :tag command to jump to a particular function (:tag ex_<Tab> is useful to get a list of all the implementations for ex-commands). I also find vim.lsp.buf.references() very useful, especially in long functions

I’d love to help write some of these!

1 Like

Given your penchant for writing excellent tutorials, I look forward to see what you come up with :slight_smile:

Yes, I can discuss Termdebug, maybe in either the GDB tutorial or compare/contrast with using nvim-dap

1 Like

Maybe an idea is a tutorial dedicated to the latest most important new stuff of NeoVim? Right now keep up also with the latest most important pull request is not easy as example too.

Also to me a tutorial is trying to understand how I can do things better compared in Neovim but not by plugins but by settings.

Another things to me is to use Quickfix better (but is just me) or for web stuff, so languages like php or html.

We’re planning on writing a newsletter for the 0.5 release, and I think TJ has mentioned doing a stream dedicated to new 0.5 features. For reference, you can follow Following HEAD · neovim/neovim Wiki · GitHub for the latest updates. I think some streamers (The Primeagen?) do videos dedicated to vim/neovim ocnfiguration.

I often think that it’d be cool to have a weekly newsletter like the
“This week in Rust” ( https://this-week-in-rust.org/ ) or “This week in
Servo” ( This Week In Servo 132 ) newsletters. It
could cover changes to neovim’s internals but also wider changes in the
ecosystem (new plugins, UIs, tutorials…).

Not sure if this is the right place to talk about this though.


I love reading the “This week” emails, especially “This week in matrix”. My only concern is that I’m not sure we would have sufficient content for a weekly content email from core alone. We could do what nix does, and have a github repo that you can submit pull requests to for the weekly email to solicit external/plugin author contributions.

I like too that kind of email.
Maybe the content can be generated automatically, as example get last repo from github with that tags like neovim or last pull requests merged, most discussed stuff from reddit/discourse and so on.
In mozilla they do a lot of that.

Another solution can be by weekly or monthly.

Estructural Regular Expression (maybe optional)

Following this article possible we could develop a lua plugin to make searches and substitutions using structural regular expressions and all the power it has.

instead of looking at a file as a sequence of lines, let’s generalize to allow arbitrary
regular expressions to mark boundaries between units. You can read
more about it at http://c2.com/cgi/wiki?StructuralRegularExpressions

1 Like