nvim-rust-by-example

Badges: coming soon

Interactive Rust by Example inside Neovim, with chapter navigation, an in-buffer table of contents, and live-editable Rust code blocks powered by mdrender.nvim.

Features

• Browse the Rust by Example book chapter-by-chapter from inside Neovim
• Open a table-of-contents picker and jump directly to any chapter
• Live-edit Rust code fences and run them in-buffer
• rust-analyzer support inside editable code blocks, including hover, diagnostics, and go-to-definition
• Inline keybinding hints for chapter navigation
• Follow markdown links to other chapters or external URLs
• Buffer-local configurable keymaps, including the ability to disable individual mappings

Prerequisites

• Neovim >= 0.10
• mdrender.nvim
• rustaceanvim
• A Rust toolchain installed via rustup

Get the Rust by Example source

Clone the upstream book with a sparse checkout so only the markdown sources are downloaded:

git clone --depth=1 --filter=blob:none --sparse https://github.com/rust-lang/rust-by-example.git ~/rust-by-example
cd ~/rust-by-example && git sparse-checkout set src

Then point src_dir at ~/rust-by-example/src.

Installation

Using lazy.nvim:

{
  "lmth/nvim-rust-by-example",
  cmd = { "RbeStart", "RbeToc", "RbeGoto" },
  dependencies = { "lmth/mdrender.nvim" },
  opts = {
    src_dir = "~/rust-by-example/src",
  },
}

Configuration

Default configuration:

require("rbe").setup({
  src_dir = "~/rust-by-example/src",
  keymaps = {
    next = "<leader>n",
    prev = "<leader>p",
    toc = "<leader>t",
    follow = "gf",
  },
})

Options

Option	Type	Default	Description
src_dir	string	"~/rust-by-example/src"	Path to the sparse-cloned Rust by Example src/ directory.
keymaps.next	`string	false`	"<leader>n"
keymaps.prev	`string	false`	"<leader>p"
keymaps.toc	`string	false`	"<leader>t"
keymaps.follow	`string	false`	"gf"

Example overriding keymaps:

require("rbe").setup({
  src_dir = "~/rust-by-example/src",
  keymaps = {
    next = "]r",
    prev = "[r",
    toc = "<leader>rb",
    follow = false,
  },
})

Commands

Command	Description
:RbeStart	Open Rust by Example from the first chapter.
:RbeToc	Open the chapter table of contents picker.
:RbeGoto N	Jump directly to chapter number N from SUMMARY.md order.

Keymaps

The following buffer-local mappings are active in Rust by Example chapter buffers by default:

Action	Default	Description
Next chapter	<leader>n	Open the next chapter in summary order.
Previous chapter	<leader>p	Open the previous chapter in summary order.
Table of contents	<leader>t	Open the ToC picker, and close it when already focused.
Follow link	gf	Follow markdown links to other chapters or external URLs.

All chapter keymaps are configurable through opts.keymaps, and any individual mapping can be disabled by setting it to false.

How it works

nvim-rust-by-example opens markdown chapters from the Rust by Example source tree and lets mdrender.nvim render them in-place. Rust fences become live-editable code blocks, backed by shadow .rs files stored under a .mdrust/ workspace next to the markdown source. rust-analyzer is attached lazily the first time the cursor enters an editable Rust block, so normal markdown browsing stays lightweight until language tooling is needed.