learn-vim asks you to read the tutorial inside the editor it teaches

The tutorial is the exercise, not the commentary

The premise is stated in the README as personal experience: it is very difficult to learn Vim by reading documentation or watching other people operate it, because you have to be in real scenarios to familiarise yourself with the commands and master them.

So the book is written as files you open in Vim. Every chapter is Markdown, readable as an explanatory document and equally usable as a working file, and the README recommends the second use.

The three commands to start are:

git clone https://github.com/dofy/learn-vim.git
cd learn-vim/en
vim chapter01.md

That third line is the entire method. You are not reading about `hjkl`, you are typing `hjkl` into a buffer that contains the next exercise.

There is also a browser option, the interactive companion at learning-vim.phpz.org with lessons and a Vim-style practice editor side by side, and its own open source repository at dofy/learning-vim. The README presents it as the alternative for people who prefer not to install anything.

The repository is multilingual at the top level: an English `en/` directory, `zh-CN/` for Simplified Chinese and `ja/` for Japanese, each with its own README linked from the root. A large part of this material originally circulated in Chinese, and the translation structure is visible rather than assumed.

Formatting conventions carry the instruction

The formatting rules are documented, and they are what makes a Markdown file usable as a lesson rather than merely a description.

Level two headings mark a major category and level three headings mark subcategories within it. Unformatted text is a normal description for reading purposes only. Text inside a block quote is an instruction to operate, and you follow what it says. Operators and commands appear in symbols such as `:w`.

The variable convention is spelled out: the `<` and `>` in commands like `f<X>` are not typed. `<X>` represents a variable, so you type `fa`, `fb` or `fC`.

And a warning that catches people out repeatedly: commands are case-sensitive, and the cases requiring attention appear in symbols such as the current line.

This is a compact notation system rather than decoration. Because an instruction is visually distinct from an explanation, you can skim the prose and still catch every thing you are supposed to type. A tutorial that formats instructions as ordinary paragraphs trains you to skim and miss them.

The chapter list follows that logic. Eleven chapters run from cursor movement through opening files and finding content, modifying and saving, tips, splits and tabs, block operations, macros, text objects, registers and clipboard, marks and jumps, and multi-file search and replace. A macro chapter before the text objects chapter is unusual ordering, and it reflects an intent to build habits rather than to present a reference order.

Your own .vimrc is the most likely reason an exercise fails

The README carries a note that deserves more attention than most tutorial authors give it. If you already have your own `.vimrc`, referenced in Chapter 4, and have changed some of the defaults in it, that may cause some operations not to match the tutorial.

The fix is to run Vim without your configuration, or with a specific one:

# Do not load the configuration file
vim -u NONE
# Load a specific configuration file
vim -u <filename>

This is a real and common failure mode. A tutorial teaches defaults, and defaults are exactly what a customised configuration overrides. Someone who has remapped a key or changed an option will hit a step that appears not to work, and the natural conclusion is that they misunderstood. Often they did not; their environment differs.

`vim -u NONE` is therefore the correct starting position for anyone who already has a Vim setup, and the README is right to put it in a callout rather than a footnote.

A second troubleshooting note covers navigation between chapters. You can navigate to the next or a related chapter and locate the file name to open it with `gf`, the goto file command. Then `:bp` goes back to the previous file, a command the README notes is covered in Chapter 2. And if you get an unsaved file error when exiting with `:q` or `:qa`, add `!` to the end of the command.

That last one is the correct instinct for a tutorial that hands you real files. You will modify a chapter by accident, and `!` is the standard answer.

Reference material sits next to the lessons, but is not the lesson

The chapters are the course. Alongside them the repository carries reference and ecosystem pages: `en/vim-modes.md` on modes, `en/vim-plugin.md` on plugins, and a `plugins/` directory with pages for NERDTree, EasyAlign, Airline with themes, and surround.vim.

Placing plugin documentation inside a beginner tutorial is a deliberate choice worth noting. The usual failure mode of teaching an editor is that the person learns commands and then meets a real configuration that may not match them. Learning what NERDTree and surround.vim do, in the same voice and the same file format as the core lessons, bridges that gap without a separate website.

The configuration recommendations section points to five setups, and the author is explicit about which one is current: dofy/nvim is the author's current Neovim setup, alongside dofy/7th-vim, kepbod/ivim, chxuan/vimplus and SpaceVim. Listing your own configuration first is a small honesty signal about what the author actually uses.

The further reading list is curated rather than long, and it says something about the ecosystem's shape. `vimtutor` is listed first as the official hands-on tutorial, described as such. Then a Chinese concise tips article, Vim Galore described as frequently updated, Daily Vim with 30 articles, another Learn Vim in English, Open Vim described as interactive, and a QuickRef cheatsheet.

Five cheatsheet links follow, in several formats including a downloadable PNG for programmers and images hosted elsewhere, plus a Star History chart.

The recommendation to run `vimtutor` before anything else is worth stating plainly: for anyone who wants one thing from this repository, the official tutorial comes first and this comes second.

Two publishing pipelines live in one repository

The project is a GitBook site, hosted at dofy.gitbook.io/learn-vim, and the repository root shows why. There is a `gitbook-docs.yaml` file for that pipeline, and separately a `.vitepress/` directory with a `package.json` that declares three scripts:

"docs:dev": "vitepress dev",
"docs:build": "vitepress build",
"docs:preview": "vitepress preview"

The build tool is VitePress at `^1.6.3`, with pnpm overrides pinning vite to `^6.4.3` and esbuild to `^0.25.0`.

Two documentation toolchains for the same content is worth a comment. The GitBook edition is the hosted one. The VitePress edition is the one a contributor builds locally with pnpm, and the overrides exist to hold transitive versions steady. Maintaining both means any structural change to the pages has to land in two places, which is a real cost that the project has chosen to carry.

The repository also contains `CLAUDE.md`, `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md` and an `assets/` directory holding the logo. The primary language is TypeScript, which reflects the documentation tooling rather than the tutorial content itself.

Worth noting for anyone who wants to contribute: the chapters are plain Markdown, so a fix to a command sequence is a text edit in `en/`, `zh-CN/` or `ja/`, and the three directories need matching changes or they drift.

CC0 content, no releases, and a maintenance date to note

Two facts about licensing need separating. The repository's licence field is CC0-1.0, the public domain dedication, which is the most permissive option available for documentation: no attribution required, no licence notice to keep, and no restriction on reuse or redistribution of the text.

The `package.json` says `"license": "MIT"`. Those cover different things, since the MIT field applies to the tooling wrapper rather than the chapters, and CC0 governs the content. For a tutorial that people might reasonably want to fork, mirror or bundle into internal documentation, CC0 is the friendlier choice and removes the question entirely.

Development status is modest and consistent. The repository is not archived, and the last push was on 2026-09-10, which is a little over a month before this article. There are no GitHub releases to consult.

For a documentation project that is the normal state rather than a warning sign. A tutorial that is not actively changing is arguably a finished tutorial. What you lose is the record of what was corrected, which matters mainly if you are reviewing the material for accuracy on a specific Vim version.

The version that matters instead is the Vim you run. The commands are for stock Vim, and the tutorial's assumption is a near-default configuration. If your Vim is Neovim, or a recent stock Vim where defaults have shifted between versions, the `vim -u NONE` escape hatch from the README is the first thing to reach for.

Editorial conclusion

Adopt learn-vim if you learn an editor by operating it and want a structured eleven-chapter path with a text-object and macro chapter that most short references skip. Do not adopt it as a Vim reference to keep open at your desk, since its structure assumes you are the one typing the commands, and treat it as one of several sources given that it recommends vimtutor, Vim Galore and cheatsheets alongside. Verify first which language directory you are reading, that your Vim matches the version the commands assume, and that running `vim -u NONE` gives you behaviour consistent with the text before you blame your own configuration.

Frequently asked questions

Official sources

1. dofy/learn-vim on GitHub
2. Issues
3. License: CC0-1.0
4. Project website
5. README