Post

Neovim Ultimate Beginner Guide | Everything You Need to Start

Do Neovim videos feel way too advanced? This one starts where you actually are: editing Markdown. We’ll work on notes and blog posts so you can focus on learning motions, text objects, and keymaps instead of fighting a full-blown codebase.

Posted Updated
Preview Image
By Christian Arzu
23 min read
Neovim Ultimate Beginner Guide | Everything You Need to Start

Contents

YouTube video

Disclaimer

  • I’m not, and I don’t intend to be a blogpost writer. I like creating videos, this blogpost is just complimentary to the video, so if something is not clear, watch the video.
  • My goal is not to create blogpost articles, yes, they’re helpful sometimes, but it’s not my main gig.
  • If you’re watching the video, this file I’m reading is a blogpost article that I create and edit in Neovim, link in the video description
  • There is a lot of keymaps and configs here that are not defaults in Neovim.
    • If you are one of them vi preppers this video and article are not for you. If you think that Neovim and vim should only be used with defaults, don’t continue, don’t waste your time and my time when reading your comments.
    • Well, ackkkshualllyyyy it’s better if you leave comments in the YouTube video, it helps with the algorithm 💅 (I’ll follow along and will try to extend our conversation as much as possible, I promise)
  • Is this only for beginners? Even if you’re an advanced user, check the video chapters, pretty sure you’ll find something useful
  • As Gregory Anders (Neovim Core maintainer) said in the Neovim vs Emacs - Roundtable w/ TJ DeVries, DistroTube, Greg Anders & Joshua Blais video: “Start small”
    • So we’re starting the way I started, which was editing markdown files for taking my notes
    • After this, Neovim became my editor for everything, and the same will happen to you too
    • I even ditched Obsidian and now I do everything in Neovim, including this blogpost and all my note taking
  • There’s a lot of “Neovim from scratch” videos, that just help you configure stuff that you don’t understand to begin with. You’ll be typing commands not having an idea of what you’re doing. This video won’t be about config, but instead focuses on practicing
  • If you know nothing about Vim motions, you will suffer, and there’s no easy way around that. I was there, everyone was there, but after a few weeks, you’ll get the hang of it. Trust me, it does not require special skills, just for you to be stubborn and stick to it

Pre-requisites

  • If you don’t want to watch the video above, and you already have your own neovim config, and want to quickly get started using my neobean config and follow along in this tutorial
  • Run the git clone commands below to clone my dotfiles in your .config directory and we will run my config below
1
2

mkdir -p ~/.config
git clone git@github.com:linkarzu/dotfiles-latest ~/.config/linkarzu/dotfiles-latest
  • Open the newly downloaded neobean config with:
1

NVIM_APPNAME=linkarzu/dotfiles-latest/neovim/neobean nvim
  • You can create an alias in your .bashrc or .zshrc file to run my config
1

alias neobean='NVIM_APPNAME=linkarzu/dotfiles-latest/neovim/neobean nvim'
  • Then to run this config, just run neobean
  • If you don’t even have neovim yet, of course you will need to install it first, so if you’re just getting started, I have a video for you:

Introduction

  • There are thousands of different ways to navigate and edit text in neovim, I don’t want to overwhelm you with every single option because:
    1. I’m not even remotely close to know them all
    2. Even if I did, you won’t remember them all at the beginning
    3. Start with these few suggestions and keep adding new stuff later on
  • I released a video that was sped up like 200%, which wasn’t very popular, so this is an updated version of that video:

Quit and save

  • It’s still good to learn the defaults
  • The traditional way:
    • To write and quit:
      • :wq
      • ZZ - shift-Z-Z (the Z’s are uppercase)
    • To quit without saving
      • :q!
      • ZQ - shift-Z-Q (uppercase too)
    • To just save, or just quit
      • :q - quit if you haven’t made any changes
      • :w - save without quitting

Neovim modes

  • Neovim has several different modes, but the ones discussed in this tutorial will be:
    • normal
    • insert
    • visual
    • command line

Normal mode

What is normal mode

  • This mode allows you to navigate and perform different actions
  • This is the mode I’m using to navigate when moving around in the video

Get to normal mode

  • The way I get to normal mode:
    • When I’m editing text (insert mode) and I want to go to normal mode, I have a keymap:
      • kj
      • This is a combination of letters almost never typed, so that’s why it works great
        • Some people prefer jj, kk or jk.
  • The traditional way:
    • [esc]
      • I re-mapped escape to capslock because it’s easier to press
    • ctrl-[

Normal mode navigation

Basic navigation

  • In neovim, instead of navigating with the arrow keys (which you also can, but not recommended), you navigate with hjkl
    • This is one of the most difficult things to get used to, trust me, we all go through it, I got defeated like 4 times before it stuck
  • Once you get used to it, you won’t have to lift your hand to look for the arrow keys, and you’ll be faster:
    • j - move cursor down by one line.
    • k - move cursor up by one line.
    • h - move cursor left by one character.
    • l - move cursor right by one character.

My top picks for normal mode navigation

  • w - moves to the start of the next word (stops at symbols)
  • e - moves to the end of the next word (stops at symbols)
  • b - moves to the beginning of the previous word (stops at symbols)
  • C-u - (ctrl+u) moves up half page
  • C-d - (ctrl+d) moves down half page
  • gg - go to the top of the file
  • G - go to the end of the file
  • 50gg or 50G - go to line 50
  • '' - (single quote 2 times) jump back to the position of the cursor before the last jump
    • Let’s say you’re in line 200, and press gg to go to the top of the file, but then want to jump back again to line 200, you press ''
    • Let’s say you’re in line 200, and press 50gg to jump to line 50, but then want to jump back again to line 200, you press ''
  • These are custom keymaps I configured:
    • gl - takes you to the last character of the line
      • Default for this is $
    • gh - takes you to the first character of the line
      • Default for this is ^
    • gj - takes me to the markdown header below
    • gk - takes me to the markdown header above

Normal mode text manipulation

My top picks for normal mode manipulation

Undo and redo
  • u - undo (press multiple times to keep undoing)
  • ctrl-r - redo (press multiple times to keep redoing)
  • . - Execute the last entered command, and leaves you in command mode:
    • Let’s say you pressed dw or db then keep pressing . to execute them multiple times
Indent
  • S+>> - (shift+>+>) indent line to the right
    • S+<< - (shift+<+<) indent line to the left
Delete, cut, copy, and paste
  • Text copied to the registry(clipboard) stays there until replaced with something else, which means it can be pasted multiple times
    • delete = cut
    • yank = copy
    • put = paste
  • d and x cuts text but also copies it to the clipboard
  • yw - yank word
  • yy - copies an entire line
  • P - paste before the cursor (or above if its a line)
  • p - paste after the cursor (or below if its a line)
  • x - deletes the character the cursor is on (leave pressed, same as supr)
  • dd - deletes entire line
  • dw - delete word starting from cursor position (stops at symbols)
  • db - deletes to the beginning of previous word (stops at symbols)
    • Useful when navigating with w and then press db
  • D - deletes until end of line, starting at cursor
  • These is a custom keymap I configured:
    • Y - yank to end of line starting from cursor
Change, replace, join
  • cw - change word starting at the cursor, leaves you in insert mode
  • r - replace a single character and automatically puts you back in normal mode
  • J - joins 2 lines together. Keep pressing it to join more lines, adds a space
1
2
3
4
5

Here I am adding some text to show you how to join lines when they are separate,

I will be pressing the keys shown above to test this, this text is just random

stuff, so do not pay attention to it
Around inside
  • All the following motions work with d, y, c, v
  • So for example you could run dap, yap, cap, vap
    • I know, it seems there should be a fap, but there’s not
  • a stands for around, deletes spaces around
  • i stands for inside, does NOT delete spaces around
    • dip - delete inside paragraph
    • yip - yank inside paragraph
    • cip - change inside paragraph
    • vip - select inside paragraph
  • Remember that instead of c below, you can switch it for y, d or v
  • caw or ciw - for a word, doesn’t matter if you’re in the middle
  • ca" or ci" - for “text in double quotes”
  • ca' or ci' - for ‘text in single quotes’
  • [ca`] or [ci`] - for text in backtick quotes
  • ca( or ci( - for (text in parentheses)
  • ca{ or ci{ - for {text in curly braces}
  • ca[ or ci[ - for [text in square brackets]
  • cap or cip - for paragraphs:
    • In the video I demonstrate this with vap and vip
  • The following work with echasnovski/mini.ai
    • cit or cat - for tags <div>change that</div>
    • This plugin can do way much more
  • vio - to select text inside a code block
    • I use code blocks a lot, so this is my favorite of all times
    • This used to work with mini.ai, not sure what happened, so I created a custom keymap
1
2
3
4
5
6

- first paragraph
- first paragraph
- first paragraph

- another line
test

There’s a lot more of these motions, if in LazyVim press ci to list them

Til (to) find
  • All the following motions work with d, y, c, v
  • So for example you could run dt7, yt7, ct7, vt7
  • Instead of [ type any character you want to find:
    • ct7, ct{, ct(, etc
  • ct[ - change til [beginning of square bracket]:
    • will delete everything from your cursor until the character 7
    • it doesn’t delete the [ itself
  • cf[ - change find [beginning of square bracket]
    • Similar to above but will delete the [

Insert mode

What is insert mode

This mode allows you to edit text as you do regularly in any editor

Get to insert mode

  • To enter insert mode there are several options, here are some useful ones:
  • i - “Insert” text before the cursor position.
  • a - “Append” text after the cursor position.
  • I - “Insert” text at the beginning of the line.
  • A - “Append” text at the end of the line.
  • o - “Open” a newline below the cursor and enter insert mode.
  • O - “Open” a newline above the cursor and enter insert mode.
  • gi - takes you back to the last position you were in insert mode

Indent text in insert mode

  • When in insert mode use <C-T> and <C-D>
  • indent this

Visual mode

What is visual mode

This mode allows you to visually select text, to then manipulate it

Visual mode navigation

  • v - enter visual mode and then move with any navigation option:
    • Using the hjkl keys
    • vgl - select to the end of the line (gl is a custom mapping I have)
    • vgh - select to the start of the line (gh is a custom mapping I have)
    • vw - select word. Keep pressing w to keep selecting words
    • Basically use any normal navigation commands when in visual mode
  • V - selects entire line
  • gv - takes you to the last selection you had in visual mode
  • vig - select entire file
    • This is a keymap that comes with the lazyvim.org distro and uses the mini.ai plugin

Visual mode text manipulation

  • Once you have text selected in visual mode, you can:
    • c - change it
    • d - delete it
    • y - yank it
    • P - paste over it
    • > - indent it to the right
    • < - indent it to the left

Pasting text in visual mode

  • When pasting text over in visual mode I personally paste with P:
    • P - does not put the REPLACED text in the unnamed "" register:
      • This means that if you paste multiple times, you will paste the original text
    • p - puts the REPLACED text in the unnamed "" register:
      • This means that if you paste again, you will paste the text that was replaced
  • Do not paste with cmd+v on macOS or it will mess up the lines you have below
1
2
3
4
5
6
7
8

Laborum aute multiple means text.
Laborum aute multiple means text.

liquip non aliquip exercitation pariatur
liquip non aliquip exercitation pariatur

do eu pariatur minim.
do eu pariatur minim.

Vertical visual mode navigation

What is vertical visual mode

This mode allows you to edit multiple lines vertically, to enter it press ctrl-v

Append same text to end of each line

  • ctrl-v - enter vertical visual mode
  • Scroll vertically to select the desired lines
  • $ - to move to the very end of every line
  • A - lowercase A to append
  • Type the desired text, you will see it only in 1 line
  • [escape] or kj - and text shows in all the lines
1
2
3
4
5

- testing line 1
- testing random 2
- testing whatever 3
- testing other line 4
- testing one new extra line 5

Insert same text at the beginning of each line

  • ctrl-v - enter vertical visual mode
  • Scroll vertically to select all the lines
  • 0 - OPTIONAL in case you’re not at the beginning of the line already
  • I - uppercase I to insert
  • Type the desired text, you will see it only in 1 line
  • [escape] or kj - and text shows in all the lines
1
2
3
4
5

testing line 1
testing random 2
testing whatever 3
testing other line 4
testing one new extra line 5

Replace same text on each line

  • Put cursor at beginning of word you want to change
  • ctrl-v - enter vertical visual mode
  • Scroll vertically to select all the lines
  • l or e - to select the rest of that word or words
  • c - c to change
  • All the selected text will be deleted and you’ll stay in insert mode
  • Type the desired text, you will see it only in 1 line
  • [escape] - and text shows in all the lines
1
2
3
4
5

new word line 1
new word random 2
new word whatever 3
new word other line 4
new word one new extra line 5

Command line mode

What is command line mode

  • You normally enter command mode when you need to enter Neovim commands like: save, quit, search, checkhealth, etc
  • : - takes you to command line mode when you’re in normal mode

Substitute

  • Anyway, it’s good to know at least this one that replaces all occurrences of “whiskey” with “juice”:
    • First enter command line mode with :, then
    • %s/whiskey/juice/g
      • % - represents all lines in the file
      • s - is to substitute
      • g - means globally (entire file)
1
2
3

whiskey word will be replaced, I have written whiskey three times, even though I
this is just some sample whiskey text that has some test words in which the
do not drink anymore, but whiskey is just the first word that came to mind

checkhealth

  • :checkhealth - allows you to see if there are errors in your neovim configuration

There’s way more

  • Most of the plugins you install have command line mode “commands”, so there’s thousands of commands that is difficult to learn by heart
  • What’s usually done, is to create keymaps to enter those commands
  • You can also create your own keymaps that execute specific actions

Relative line numbers

  • Let me tell ya that relative line numbers are a bitch
  • I’ve tried those MFs for like 5 different times and I always say, fuck relative line numbers and always turn them off.
  • But they’re useful as shown in the video

Use ctrl+u and ctrl+d a lot

  • Use this to navigate half page at a time, I think I modified it so it’s a bit less, than half a page, but you get the point

What is hardtime.nvim

  • m4xshen/hardtime.nvim
  • This is the plugin that got me used to relative line numbers
  • At first you will feel like cheating:
    • Using the arrows (yikes, disgusting),
    • Pressing only j and k to travel your file up and down, I did this for sooooo long
  • Hardtime is enabled by default in my config
  • I’d suggest you to leave it on, I modified the defaults a bit to make it less strict
    • Alright, if you feel like going and crying to your mommy because all of this is too difficult, you can disable it while you get started
  • Mastering Neovim Jump Motions and Jumplist - hardtime.nvim + Better Navigation Habits

Use flash.nvim to jump to sections

I navigate markdown files faster with folds

  • I mainly use zk, zl and zi
    • These are not folding defaults, so if you’re a defaults sensitive person, I don’t know why you’re still reading, just GTFO
  • This allows me to navigate markdown files way faster
  • Now, I rarely use outline.nvim

Jump to diagnostics, spells, etc

You will feel like reinventing the hjkl wheel

  • Once you get a little bit of experience, you will feel like an overlord, and think that you came up with a better plan than billions of people that have used vim in the past years:
    • Remapping hjkl to jkl;, and let me tell ya something:
      • I’m in favor of remapping stuff and moving out of defaults when it makes sense, that’s why this blogpost will not be liked by so many 90 year olds that like sticking to defaults. So when the day finally comes to diffuse a bomb using stock motions, they can achieve it (Thorsten Ball words, not mine
      • But please, do not commit this aberration
      • EVERY other tool out there that uses vim motions, like kindaVim for mac, Homerow, even a basic tool like the Raycast app launcher use vim motions. And guess what, all of them use navigation the way the lord intended, with hjkl
      • If that’s not the case, my config has some keymaps that assume h is left and l is right, like gh ad gl
      • So please, do yourself and every other vim user you know a favor: Don’t change this
      • I’ve warned you, and if you do, don’t tell anybody, because they’ll look at you different (just suffer in silence and stay anonymous)
    • Quick kindaVim, homerow, Raycast demo

Search, find replace

Search find

This is useful if you open a file with neovim, and need to search for a specific word

  • For all the following options:
    • n - keep searching the same word forward
    • N - keep searching the same word backward
  • /unicorn[enter] - search forward for the word “unicorn”
  • ?unicorn[enter] - search backward for the word “unicorn”
  • * - moves to the next occurrence of the word where the cursor is
  • # - moves to the prev occurrence of the word where the cursor is:
    • opposite of *

echasnovski/mini.surround

  • echasnovski/mini.surround
    • This is a plugin I cannot live without, I highly recommend you to get it
    • This already comes in my own config in case you want to test it out
  • Add a surround on a word
    • Position the cursor at the beginning of the word
    • Add the surround with gsae", for example
    • e above is to move to the end of the word
      • Besides ", I also use these: ` ‘ ( [ {
  • Add a surround in visual mode
    • If I want to surround a part of the text
    • I select it in visual mode, then press gsa"
      • Besides ", I also use these: ` ‘ ( [ {
  • Replace a surrounding
    • Let’s say I have this [ surrounded text ]
    • And I want to change it with ‘surrounded text’
    • Place the cursor anywhere inside the “ “
    • Then press gsr"'
      • goto, surround, replace, current surrounding, new surrounding
  • Remove a surround
    • If we have ‘this surrounded text’
      • Place cursor anywhere inside the surrounding and remove it with gsd'

Tutor

What do do next?

You’re a fraud, why do you ask for money, isn’t YouTube Ads enough?

neovim
macos tutorial youtube video neovim neobean
This post is licensed under CC BY 4.0 by the author.