DEV Community: Jake Wiesler

Essential Vim Movements

Jake Wiesler — Sun, 21 Nov 2021 15:17:29 +0000

I’ve been using Vim for just over a year. A combination of the Vim emulator in VSCode and Neovim in the terminal. The former is a great way to start familiarizing yourself with the basics before you jump into the latter. In this post, I want to walk through some of the movements I use everyday to traverse files quickly.

Up, down, left and right
Up, down, left and right, but faster
- Tip: Use the scrolloff setting
Jump to the beginning of a line
Jump to the end of a line
Jump to a specific line
- Tip: Use relative numbers
Search for text

Up, down, left and right

These are the first four movements anyone questing in Vim-land will learn. They are executed with the h, j, k and l keys:

h - move left
j - move down
k - move up
l - move right

You can think of these four letters as flattened arrows, the ones you’d normally find on a keyboard.

Up, down, left and right, but faster

Getting comfortable with hjkl will take time, but eventually you’ll be looking to traverse documents faster. You can achieve more speed in each direction using the following keys:

w - move forward to beginning of next word
b - move backward to beginning of previous word
Ctrl-u - move halfway up the screen
Ctrl-d - move halfway down the screen

I tend to use the keys above much more frequently, usually to locate a specific part of the file. I'll then rely on the hjkl keys for pinpointing specific characters.

Tip: Use the `scrolloff` setting

This one isn't a movement per se, but it will really improve your experience when you start utilizing vertical movements like Ctrl-u and Ctrl-d. Without overriding the default value of scrolloff, the minimal number of lines above and below the cursor will be 0. This results in your cursor being potentially locked to the first or last line of the file depending on the direction you are heading.

It's kind of annoying.

I would suggest overriding the default value with a number you feel comfortable with:

" .vimrc

set scrolloff=8

The configuration above will maintain, at minimum, 8 lines above or below the cursor based on your location in the file while scrolling. You can think of it as a padding of sorts.

This is an improvement, but I like to take it further:

" .vimrc

set scrolloff=999

With the value 999, you can force the cursor to stay in the middle of the file in most scenarios. This prevents your eyes from jumping around looking for the cursor, as it will usually be in the middle of the screen until your reach the beginning or end of the file.

Jump to the beginning of a line

This can be achieved in a few ways, depending on what your needs are:

^ - Go to the first character in the line
0 - Go to the first column in the line
Shift-i - Place the cursor before the first character in the line, and enter INSERT mode

^ and 0 are almost the same. Their difference occurs when the line you're on is indented. ^ takes you to the first non-blank character in a line. 0 will always take you to the start of a line, even if there is no character there.

Shift-i is useful when you want to navigate to the beginning of a line and start typing immediately.

Jump to the end of a line

Similar to jumping to the beginning of a line, we can also jump to the end of a line using the following keys:

$ - Go the last character in the line
Shift-a - Place the cursor after the last character in the line, and enter INSERT mode

Jump to a specific line

There are a few ways to jump to a specific line, and they all involve the letter "G".

gg - Jump to the first line in a file
G - Jump to the last line in a file
35G - Jump to line number 35

I use gg and G pretty heavily. They're great ways to go north and south, especially if you know what you're looking for.

The last example shows how to jump to a specific line number, in this case line 35. If you type a line number that is beyond the max line number in the file, you will just go to the last line.

Tip: Use relative numbers

If you read my Getting Started With Vim article, you may have added the following general settings to your Vim configuration:

" .vimrc

" add line numbers
set number
" add width to line numbers
set numberwidth=4

These are must haves in my opinion, but if you are going to leverage line
numbers while navigating files in Vim, you may want to consider adding a new
setting:

" .vimrc

set relativenumber

The relativenumber setting shows line numbers relative to the line you are
currently on. In the example below, the cursor is on line 12, and the lines
above and below are numbered 1, 2, 3 and so on.

Why do I suggest this? Using relativenumber enables even more efficiency when
traversing north and south:

3j - Jump down 3 lines
8k - Jump up 8 lines

Using j and k without line numbers as a prefix will go 1 line down and up
respectively. So this should feel pretty natural once you use it a few times.

These movements are still possible without the relativenumber setting on, but
it is harder to identify how many lines up or down you want to jump.

Search for text

To search for a specific text pattern in a file, you can prefix the pattern with
a forward slash /:

/my-word - Searches the file for the text pattern "my-word"

Once you complete typing out the pattern to search for, be sure to hit ENTER.
This will jump you to the first occurrence of the pattern in the file. If there
is more than one match, you can jump between them using the following keys:

n - Jump to next occurrence of text pattern
Shift-n - Jump to previous occurrence of text pattern

Tip: Improve search experience

Here are a few settings that can improve your search experience:

" .vimrc

" Disable highlighting of all search results
set nohlsearch
" Only highlight first search result
set incsearch
" Default to case insensitive search
set ignorecase
" Use case sensitive search if pattern includes uppercase letter
set smartcase

Conclusion

If you made it until the end, thanks for reading! I hope this article has been useful to you. I'm still very raw with Vim, but the movements described above have served me well. If you are new to the text editor, please give these a try and stick with it! You'll be surprised at how fast you adapt. It's all muscle memory!

I will do my best to keep this document updated as I progress with Vim and learn new ways to do things. If you have any suggestions, let me know on Twitter! And as always, happy building!

Setup Zsh As Your Default Shell

Jake Wiesler — Sun, 21 Nov 2021 15:10:55 +0000

If you're switching from Bash to Zsh and you want to know how to launch new terminal sessions in Zsh, you've found the right blog post. I've had to do this a few times over the years, and it was always a struggle. Recently I started working on a portable development environment and I learned how to set Zsh as my default shell the right way. Here's how:

Prerequisite: Install Zsh

How you install Zsh is up to you. Checkout this GitHub gist for some OS-specific options. The following steps will work for any Linux/Unix-based machine. I am not aware of how to accomplish this on Windows.

Step 1

The first step is to tell your terminal that Zsh can be used as a valid login shell. You do this by updating a special file named /etc/shells. If you cat this file:

cat /etc/shells

You will see a list of filepaths that each point to an executable file.

# List of acceptable shells for chpass(1).
# Ftpd will not allow users to connect who are not using
# one of these shells.

/bin/bash
/bin/csh
/bin/dash
/bin/ksh
/bin/sh
/bin/tcsh

The output above may vary depending on your circumstance. One of these executables is your current shell. You can see your current shell by running:

echo $SHELL

The output of the command above will be an executable file that resides within the /etc/shells list. For example, if I run the echo command above, the output I see is:

/bin/bash

Locate Zsh's executable filepath

We need to append the Zsh exectuable to this list, but before doing that we need to know where it is. To find its location you can run the following command:

command -v zsh

command -v will print the absolute filepath used when invoking the argument provided, in this case zsh. This gives us the path to Zsh's exectuable file. The location may vary depending on your installation method.

For example, running the command above may yield:

/bin/zsh

If you see no output at all, then you probably don't have Zsh installed. See Prerequisites.

Append Zsh's executable filepath to `/etc/shells`

Once we have the location of Zsh's exectuable file, we can "pipe" it to another command:

sudo tee -a /etc/shells

The tee utility, which we are running in sudo, takes an input and appends it to /etc/shells.

Together, the full command is:

command -v zsh | sudo tee -a /etc/shells

The | is the pipe symbol. It takes the output of the left-hand side and uses it as the input for the right-hand side. In psuedo, what's happening is:

Locate the filepath of Zsh
Append the filepath to /etc/shells

After running the full command you should see Zsh's executable at the bottom of /etc/shells.

Step 2

Now that we've told our terminal that Zsh can be used as a valid login shell, we need to explicitly use it as the default. This can be accomplished with the following command:

sudo chsh -s $(which zsh) $USER

The command above is chsh -s, or "change shell". We are running it in sudo mode for elevated permissions, and we pass it two arguments:

$(which zsh) - The shell we want to use as the default
$USER - The user whose default shell we are changing, ie. - you.

After running this command, the next time you start a new terminal session you will see Zsh! To confirm, you can run:

echo $SHELL

Conclusion

And that's it! Running the commands defined in steps 1 and 2 will turn Zsh into your new default shell. If you have any further questions, or maybe you have a better way of doing this, let me know on Twitter!

Getting Started With Vim - A Practical Guide

Jake Wiesler — Sun, 17 Oct 2021 00:00:00 +0000

So you want to use Vim full time do ya? It’s not going to be easy, but I believe the choice is worth it. I made the switch from VSCode to Vim a few weeks ago. I’ve been diving deep and learning a ton, and I still feel like I’ve only scratched the surface. To be honest, I don’t even feel qualified to write this post. But my recent efforts have to count for something, right?

Vim presents you with a thousand roads to wander. There is no shortage of configuration options, plugins and unfamiliar syntax, leaving newbies like us lost and paralyzed with decision fatigue. If this is how you feel, you’re not alone. But I urge you to push through.

Vim can be an incredibly powerful tool in your arsenal. When you have it tuned to your liking, it's an absolute joy to use. This post is aimed at guiding you through the difficult bits so you can get to the joyful bits as fast as possible. I will go through everything I know so far, helping you go from 0 to 1.

We will create a strong foundation that you can build on over time. One that gets out of your way and allows you to produce your best work. So grab a coffee (maybe 2) and get your mind right. We will dine in the gates of Vim this day!

Neovim
General Settings
Plugins
- Manage plugins with vim-plug
- Pick a color scheme
- Search with telescope
- Better status lines with lightline
- Git integration with vim-fugitive
- gitsigns for git decorations
Language Support
- Using lspconfig
- Language servers
- Autcompletion with nvim-cmp
Remaps
Tips and Tricks

Neovim

Instead of using good ole’ Vim, the one that comes preinstalled on your MacOS or Linux machine (sorry Windows users), we will opt to use Neovim. If you’re unfamiliar, Neovim “is not a rewrite but a continuation and extension of Vim”. There isn’t much difference between Vim and Neovim from a user’s perspective. However, Neovim is optimized out-of-the-box and has an active development team that is pushing the tool to greater heights quickly.

Installation

First, you’ll need to install Neovim on your machine. There are many ways to do this. I use MacOS and opted for Homebrew:

brew install neovim

Once the install is complete, you can test that it’s working by using the following command in your terminal:

nvim --version

init.vim

Vim uses a .vimrc file to hold your configuration settings, but Neovim is a little different. It uses an init.vim file located at the path:

~/.config/nvim/init.vim

The ~/ represents your home directory. You might already have a ~/.config directory, as it is common amongst other tools. Whatever your situation, you will want to create an init.vim file at the path above.

mkdir -p ~/.config/nvim
cd ~/.config/nvim
touch init.vim

In this file, you can define general settings, plugins, color schemes, keybindings (called remaps) and more.

General settings

Now that your config file is created, let’s open it up:

nvim init.vim

The file will be empty. Let’s add some basic settings:

" enables syntax highlighting
syntax on

" Better colors
set termguicolors

" number of spaces in a <Tab>
set tabstop=4
set softtabstop=4
set expandtab

" enable autoindents
set smartindent

" number of spaces used for autoindents
set shiftwidth=4

" adds line numbers
set number

" columns used for the line number
set numberwidth=4

" highlights the matched text pattern when searching
set incsearch
set nohlsearch

" open splits intuitively
set splitbelow
set splitright

" navigate buffers without losing unsaved work
set hidden

" start scrolling when 8 lines from top or bottom
set scrolloff=8

" Save undo history
set undofile

" Enable mouse support
set mouse=a

" case insensitive search unless capital letters are used
set ignorecase
set smartcase

I’ve collected these settings from community suggestions and others' dotfiles. I believe they are a great base without being too opinionated. Comments have been added for each setting to give some insight as to what they do. If you want more information on each, you can type :h <setting-name> inside Neovim to bring up the help manual for that specific setting. For example:

:h incsearch

Will bring up the help section for the incsearch option.

Note: If you have suggestions on other settings to include, let me know on Twitter!

Plugins

Now that we have some basic settings out of the way, let’s get to the fun part. Plugins! In Vim, plugins are scripts that operate in a global scope or per filetype. Authoring these plugins is done in Vimscript. I’ve never worked with Vimscript, but I’ve heard it’s tricky, and a barrier to entry for developers who want to build plugins or contribute to Vim’s core.

Neovim’s vision is to:

Enable new contributors
Remove barriers to entry
Unblock plugin authors
Deliver a first-class scripting alternative to Vimscript

This alternative scripting language is Lua. Neovim still supports Vimscript, but the core development team encourages plugin authors to write plugins in Lua. I’ve only been exposed to the language for a few weeks, but it is relatively simple to understand. Here are a few resources if you’d like to learn more:

You will need to use Neovim for a little bit before you can understand where your pain points are. For this reason, I’m going to keep my list of plugin recommendations short. I will only recommend plugins that I feel are “blue chips” in the Neovim community.

That being said, both Vim and Neovim make it easy to pop plugins into your configuration and try them out for an hour or two. If you like them you can stick, but you don’t have to marry anything.

vim-plug

In order to install plugins we need a plugin manager. Enter vim-plug. There are other options that I have my eye on (looking at you packer.nvim), but for now we will use vim-plug. It has 25k stars on GitHub, so I think we’re in good hands.

To install it you can checkout the docs in the GitHub repository. Once installed, we’ll add a few lines to our init.vim:

" ...general settings

call plug#begin('~/.config/nvim/plugged')

" plugins will go here

call plug#end()

We call plug#begin(), passing in the directory where we want to install our plugins, and plug#end(), which signifies the end of our plugin declarations.

But we haven’t declared any…yet!

A color scheme

Most colors schemes in Neovim can be installed as a plugin. A color scheme is 100% preference, and there are a lot of really good ones. Here’s a list of some of my favorites:

Inside of plug#begin() and plug#end() , let’s declare our color scheme. I will use Gruvbox to illustrate:

" ...general settings

call plug#begin('~/.config/nvim/plugged')

Plug 'gruvbox-community/gruvbox'

call plug#end()

The above example illustrates how to declare plugins you wish to install with vim-plug. It is shorthand notation for:

Plug 'https://github.com/gruvbox-community/gruvbox'

You can see more examples of declaring plugins with vim-plug here.

Once you declare your plugin in init.vim, you need to take a few more steps to install it:

Save your init.vim with :w
Source your init.vim with :so %
Run :PlugInstall

The commands above need to be entered in NORMAL mode. See here for an explanation on Vim’s “modes”.

Step one saves your init.vim file without closing it.

Step two “sources” your init.vim. The command is shorthand for :source CURRENT_FILEPATH.

Step three calls a global function named PlugInstall which is made available to you by vim-plug. It will open a vertical buffer to the left of your init.vim. In this buffer you will be able to see a list of all the plugins you’ve installed along with the most recent installation’s progress. Once the plugin has finished installing, you can close the vim-plug buffer by typing :q!.

After installing your color scheme, we’ll need to tell Neovim to use it. Inside of your init.vim and below your plugin declarations, add the following lines of code:

" ...general settings

call plug#begin('~/.config/nvim/plugged')

Plug 'gruvbox-community/gruvbox'

call plug#end()

" declare your color scheme
colorscheme gruvbox
" Use this for dark color schemes
set background=dark

If you aren’t using gruvbox then make sure to refer to your color scheme’s documentation for clear instructions on how to declare it.

Save and exit with :wq. Next time you reopen Neovim you should see a crisp new paint job!

Telescope

The first function-focused plugin on the list is Telescope, created by one of Neovim’s core team members - TJ Devries.

Side note, TJ puts out a lot of Neovim-related content on his YouTube channel and his Twitch streams. His YouTube channel in particular has been a great resource. Check him out!

Telescope is a must-have plugin in my opinion. It is a fuzzy finder built in Lua that can be configured every which way. It adds a ton of functionality to your Neovim setup. I haven’t realized its true potential so far, but for finding files and searching for text it’s amazing.

Let’s install it:

" ...general settings

call plug#begin('~/.config/nvim/plugged')

" ...plugins

" Telescope requires plenary to function
Plug 'nvim-lua/plenary.nvim'
" The main Telescope plugin
Plug 'nvim-telescope/telescope.nvim'
" An optional plugin recommended by Telescope docs
Plug 'nvim-telescope/telescope-fzf-native.nvim', {'do': 'make' }

call plug#end()

Note that we are installing more than one plugin here. Telescope requires another plugin named plenary to function. And the other plugin is a Telescope Sorter that supports fzf syntax. Telescope recommends installing it for performance improvements. We like the gains, so we’ll take the gains.

Make sure to perform these three steps to complete installation:

Save init.vim with :w
Source init.vim with :so %
Install the plugins with :PlugInstall.

Next we need to configure Telescope. This is a common practice amongst Vim plugins, and in my opinion the most challenging aspect of Vim. If you’re working with a Vimscript-based plugin it can be even more so. This is why I’ve tried to stick to Lua-based plugins when possible.

Telescope happens to be a Lua-based plugin, which is awesome! Since it’s the first plugin on the list, we’ll need to do some basic setup.

First, we will need to create a new directory in ~/.config/nvim named lua:

cd ~/.config/nvim
mkdir lua

Inside of the lua directory we want to create a subdirectory to namespace our plugin configurations. To understand why this is necessary requires explaining how Vim handles file lookup. In short, creating a namespace subdirectory inside the lua directory prevents unwanted filename collisions.

I’ve opted to use my GitHub handle as the name of my subdirectory:

cd ~/.config/nvim/lua
mkdir jakewies

You can make it whatever you like. It really doesn’t matter. Once you’ve created it, you’ll want to cd into it:

cd ~/.config/nvim/lua/YOUR_NAMESPACE

Note: YOUR_NAMESPACE is being used as a placeholder. Replace it with the name of your namespace directory.

In your namespace directory you will create a .lua file for every plugin you want/need to configure. Telescope is the first one:

nvim telescope.lua

A helpful Vim tip is that you can open files before they exist. If you close the file without saving it, it won’t be created! In the example above, we open telescope.lua in Neovim. As long as we save the file it will be created.

Our configuration for Telescope will be short and sweet:

local telescope = require('telescope')

telescope.setup {}

-- To get fzf loaded and working with telescope,
-- you need to call load_extension, somewhere after
-- the setup function.
telescope.load_extension('fzf')

The above example gives us our first taste of Lua. See? Not that intimidating! I’ve found that, at a minimum, a lot of plugins need:

require('PLUGIN_NAME').setup {}

I won’t be diving deep into Telescope configuration in this post. If you want to see some of the available setup options and other customizations, check the docs.

Make sure to save telescope.lua and exit Neovim with :wq.

Next, we need to tell our init.vim that it exists:

" ...general settings
" ...plugins

lua require('YOUR_NAMESPACE/telescope')

In my case I would put:

lua require('jakewies/telescope')

A couple of notes:

Put this command below the vim-plug functions!
You don’t need to specify the .lua filetype

What does this do? It seems a little magical at first, and understanding requires Vim lookup knowledge, but essentially this command will look for a lua folder in your Vim runtime, and source the specific .lua file based on the path. So in this example the following file will be sourced:

~/.config/nvim/lua/YOUR_NAMESPACE/telescope.lua

This is great! But we can certainly improve on it.

Instead of requiring each configuration file in our init.vim, we can just require the namespace directory. In order for this to work, we’ll need to add a new file to our namespace directory called init.lua:

cd ~/.config/nvim/lua/YOUR_NAMESPACE
touch init.lua

The init.lua file can be thought of as an index file, similar to index.js for you JavaScript friends. Inside init.lua we can require all of our configuration files:

require('YOUR_NAMESPACE/telescope')

Now, inside of our init.vim all we need to do is require the namespace:

" ...general settings
" ...plugins

lua require('YOUR_NAMESPACE')

In my case it would be:

lua require('jakewies')

From this point on, any new configuration files in lua/YOUR_NAMESPACE can be required within lua/YOUR_NAMESPACE/init.lua and they will be sourced in your init.vim!

Ok, back to Telescope.

Telescope exposes a number of commands that can be accessed using :Telescope in NORMAL mode. A quick way to see all of the available commands is to enter :Telescope followed by a space, and then hit <Tab>. The tab button will open an autocomplete list full of available Telescope commands. You can navigate the list using <Tab> and <Shift-Tab> to go backwards.

Below are a list of Telescope commands that I have found extremely useful thus far:

:Telescope find_files

- This command will search your current directory for filenames matching your query. It will not show hidden files by default, and it will also ignore files in `.ignore` files like `.gitignore`.

- This command will also try to identify if you are in a larger project using special directories like `.git`. This gives you access to subdirectories and parent directories if you have moved away from the project root.

:Telescope buffers

- Search for files that have been opened in a buffer in your current Neovim instance. Really helpful when you are working on a few files at a time, and you want to “narrow your world”.

:Telescope live_grep

- Similar to `find_files`, but searches for a string match rather than a file name. [Note, this command will only work if you have `ripgrep` installed](https://github.com/nvim-telescope/telescope.nvim#suggested-dependencies). `ripgrep` is a command-line search utility that makes searching for text really fast. It can be installed like any other command-line tool, and Telescope will use it for its `live_grep` command.

The commands above are just a few I’ve been leaning on lately, and there's many more. Another helpful tip is to think about mapping the commands above to a keybinding. For instance, I have the find_files command mapped to <Ctrl-p>.

You can view documentation on Telescope within Neovim using:

:h telescope

Lightline

Lightline is a status line plugin for Vim. The status line exists at the bottom of your Vim window, and exposes a few helpful pieces of information, such as the current MODE (normal, insert, visual, etc.), and what type of file you are in.

I enjoy developer tools that do a small list of things well without trying to support every use case under the sun. Lightline fits that mold. It is relatively “light” in configuration options when compared to other popular alternatives like vim-airline.

To install Lightline, let’s open up our init.vim again:

" ...general settings

call plug#begin('~/.config/nvim/plugged')

" ...plugins

" Lightline
Plug 'itchyny/lightline.vim'

call plug#end()

Remember, each time you declare a new plugin you have to take 3 steps to get it installed:

Save your init.vim with :w
Source your init.vim with :so %
Run :PlugInstall

We will preemptively create a configuration file for Lightline now, because shortly we will install a plugin that integrates with the status line in a unique way.

In our namespace directory, let’s create a lightline.lua file:

cd ~/.config/nvim/lua/YOUR_NAMESPACE
nvim lightline.lua

Inside the file, we’ll add a placeholder config object:

vim.g.lightline = {}

The config above looks different from that of Telescope’s. The reason for this is that Lightline is not written in Lua, and so to hook into its configuration requires using the Vim namespace within the Lua standard library:

Neovim exposes a global vim variable which serves as an entry point to interact with its APIs from Lua. It provides users with an extended “standard library” of functions as well as various sub-modules.

vim.g is a meta-accessor that lets you interact with Vim’s global variable. The config above sets a new global variable named lightline to an empty object.

Go ahead and save your lightline.lua file before sourcing it within your namespace directory’s init.lua file:

require('YOUR_NAMESPACE/telescope')
require('YOUR_NAMESPACE/lightline')

My init.lua currently reads:

require('jakewies/telescope')
require('jakewies/lightline')

Save init.lua with :w and source it with :so %.

One last thing we want to do is hide the Vim Mode text at the bottom left of our window. This is no longer necessary since Lightline is showing us the mode too.

In your init.vim file, append the following setting to your General Settings:

" ...general settings
set noshowmode

Excellent! That wraps up the Lightline section for now. If you want to view documentation on Lightline in the future, you can do so within Neovim using:

:h lightline

vim-fugitive

If ever there was a “blue chip” plugin in the Vim ecosystem, vim-fugitive would probably be it:

A Git wrapper so awesome, it should be illegal.

It has taken some getting used to, but the integrations provided by vim-fugitive are powerful. Let’s install it. You know the drill by now:

" ...general settings

call plug#begin('~/.config/nvim/plugged')

" ...plugins

" vim-fugitive
Plug 'tpope/vim-fugitive'

call plug#end()

There’s no configuration required for this plugin. Just save, source, install and you’re off to the races.

I have a very familiar workflow with Git via the command line. Trying to re-train my brain to utilize vim-fugitive is going to take some time. You might be in a similar boat, so let me give you some helpful tips.

:Git

This is the “crown jewel” (straight from the Docs!) of vim-fugitive. As you may have come to recognize with these types of commands, you can use <Tab> autocomplete to see what else it can do:

:Git <Tab>

And there is a lot you can do! In fact, it’s a little overwhelming, but if you’re familiar with Git, then you will find vim-fugitive is pretty intuitive:

" view status of current branch
:Git status

" view available branches
:Git branch

" stash work
:Git stash

" stage changes for commit
:Git add

" commit staged changes
:Git commit

" push committed changes
:Git push

Entering :Git with no command will bring up the fugitive-summary window. I actually like this feature a lot. You will see a list of untracked, staged and unstaged files along with the current branch name. Placing your cursor over these files will let you run certain “maps” like staging/unstaging, discarding changes, toggling inline diffs etc.

For more info on what maps are available within the fugitive-summary window, enter:

:h fugitive-maps

Or check out this link.

vim-fugitive can integrate with Lightline to display the current working branch. Let’s set that up. In our placeholder lightline.lua file from before, let’s add some configuration:

vim.g.lightline = {
    active = {
        left = {
            { 'mode', 'past' },
            { 'gitbranch', 'filename', 'modified' }
        }
    },
    component_function = {
        gitbranch = 'fugitive#head'
    }
}

There’s a lot going on here, but know that this comes straight out of Lightline’s README in the Advanced Configuration section. In short, we define a component named gitbranch and set it equal to fugitive#head, and then add the component to the left side of the status line.

Save and source the file. If you are working in a git project (pssst. you should!) , you will see the branch name on the bottom left!

For more information on vim-fugitive enter the following command in Neovim:

:h fugitive

gitsigns

One thing I sorely miss from VSCode is the ability to view new, modified and deleted lines in a git project. Neovim doesn’t support this by default, so we’ll use gitsigns:

Super fast git decorations implemented purely in lua/teal.

Yes please. In our init.vim:

" ...general settings

call plug#begin('~/.config/nvim/plugged')

" ...plugins

" gitsigns
Plug 'lewis6991/gitsigns.nvim'

call plug#end()

Note: gitsigns requires nvim-lua/plenary.nvim as well. Since we’ve installed this with Telescope (see above), we’re covered.

You know what to do - Save, source and :PlugInstall.

Gitsigns requires calling a setup function in your configuration for it to work. Let’s create a gitsigns.lua file in our namespaced directory:

nvim ~/.config/nvim/lua/YOUR_NAMESPACE/gitsigns.lua

And inside of this file we’ll get things started:

require('gitsigns').setup {}

Passing no options will init the plugin using the default settings, which can be found here.

Now let’s add gitsigns.lua to our namespace directory’s init.lua file:

require('YOUR_NAMESPACE/telescope')
require('YOUR_NAMESPACE/lightline')
require('YOUR_NAMESPACE/gitsigns')

Mine looks like this:

require('jakewies/telescope')
require('jakewies/lightline')
require('jakewies/gitsigns')

Source this file and you’re good to go! You can see gitsigns in action by navigating to a project on your machine that is version controlled with git. Any tracked file that has been modified will display that modification with a colored pipe on the left hand side of Vim.

Although this is technically what we want, the placing of the sign is a little off. This is because we need to tell Vim to show diagnostics signs in the number column, rather than to the left of the number. Open up your init.vim file and add a new set option to your general settings:

" ... general settings
set signcolumn=number

Save and source your init.vim file and view the changes. Now your signs should be displayed in the number column, rather than to the left. To learn more about the signcolumn option, run the following command in Neovim:

:h signcolumn

Git signs also supports a Git blame feature very similar to VSCode, and it’s a feature I desperately miss. When you are in a project that uses Git, keeping your cursor over a line for a certain period of time will cause some virtual text to display in a dim color. The text will read the name of the developer that last modified the line, the modification date and the commit message.

I love this feature, but it’s not a requirement. vim-fugitive has a :Git blame command that solves the same use case, but I prefer the virtual text. To enable it, simply add the following to your Git signs configuration:

require('gitsigns').setup {
    -- signs config
    current_line_blame = true,
    current_line_blame_opts = {
        virt_text_pos = 'right_align'
    }
}

And that’s it! Saving and sourcing the file will result in some inline Git blame goodness.

Language support

At this point we have some general settings applied that make Neovim easier to work with. We have some plugins installed that improve our productivity. But we still haven’t done anything about language support.

In text editors like VSCode, this isn’t a huge concern. Some languages like JavaScript and HTML are supported out of the box. Others, like Python and C++, have dedicated extensions that make your life a lot easier. These extensions provide Intellisense, code completion, formatting, linting and more.

Extensions like this are possible because VSCode supports the Language Server Protocol, a Microsoft-created standard for defining communications between language tooling and text editors.

Before the Language Server Protocol (LSP), language tools and text editors had no uniform way of talking with each other. Each language tool needed a separate implementation for each editor, and each editor needed to adapt to each tool.

LSP provides a reliable standard so language tools can be built once, and editors that support LSP will be able to utilize them.

Neovim supports LSP natively as of v0.5.0, meaning we can get the same benefits VSCode provides, albeit with a “little” configuration.

There is a second option to Neovim’s native LSP called coc.nvim. It has been around for a while and a lot of people use it with success. I showed up to the Neovim party around the time that native LSP became a thing, so I never really tried coc. I’ve heard that it is much easier to configure, but comes with significant features that you may or may not need.

I like the idea of opting for the native solution when possible, and even though it can be a pain to configure at the moment, the fact that the core team is supporting LSP means that in the future things should improve. For this reason, we’ll opt for native LSP, but feel free to check out coc if things get dicey.

Note: In order for the rest of this section to work for you, make sure you are on v.0.5.0 of Neovim or above.

Lspconfig

To get started with Neovim’s native LSP, we need to install a few plugins. The first is nvim-lspconfig. Per the README, this plugin:

Handles automatically launching and initializing language servers that are installed on your system.

We can install it the same we install any other plugin in our init.vim file:

" ...general settings

call plug#begin('~/.config/nvim/plugged')

" ...plugins

" LSP
Plug 'neovim/nvim-lspconfig'

call plug#end()

Remember to save, source and :PlugInstall!

Install a language server

The next step is installing the necessary language server(s) for your development environment. This is equivalent to installing a VSCode language extension. Neovim lists available language servers here. Find one that supports your language of choice, and install it on your machine.

For example, I work with Typescript every day, so I need to install a Typescript language server. The list of available servers tells me that I should install tsserver. It can be installed via npm globally like so:

npm install -g typescript typescript-language-server

A few things to note here:

You are not installing the language server as a Neovim plugin. You are installing the server as a global package on your computer.
Not all language servers are installed the same. tsserver can be installed via npm, but others may require different installation methods.
Always refer to the list of available language servers to find the one you need. If installation instructions are not provided, look at the server’s official README.

Configure the language server

After you have successfully installed your language server(s), it’s time to tell Neovim about them. This is going to be the most challenging aspect of setting up native LSP. I am still trying to understand all the moving parts!

Let’s create a new .lua file in our namespace directory called lsp.lua:

nvim ~/.config/nvim/lua/YOUR_NAMESPACE/lsp.lua

This file will hold all of our LSP-related configuration. Inside, we need to add some boilerplate code. Note that the code we are adding here is not only documented on the lspconfig README, but it’s also the recommended configuration by Michael Lingelbach, one of Neovim’s core team members, who has worked heavily on the native LSP implementation.

I will walk through setting up this file step-by-step using tsserver is an example.

-- lspconfig
require'lspconfig'.tsserver.setup {}

The code above is a minimal representation of how we can get Neovim’s LSP working with tsserver. This works just fine, however we can improve on this:

-- lspconfig
local nvim_lsp = require('lspconfig')
local servers = { 'tsserver' }

for _, lsp in ipairs(servers) do
    nvim_lsp[lsp].setup {}
end

The code above is now capable of setting up any arbitrary amount of servers defined in the servers variable. Installing more than one server? This will effectively loop through each one and wire it up to nvim_lsp.

For example, maybe you added a few more language servers to your setup:

local servers = {'clangd', 'pyright', 'tsserver'}

The only thing that has to change in your code is the servers variable. Everything else can stay the same!

Note: ipairs is a lua function that returns index-value pairs. We don’t need the index, hence the _.

Each server’s setup function is capable of accepting a special on_attach function that runs when a server attaches to your current Neovim buffer. Think of the current buffer as the current file you are editing in Neovim. Based on the filetype, you can have LSP configured to do certain things.

-- lspconfig
local nvim_lsp = require('lspconfig')
local servers = { 'tsserver' }

local on_attach = function(client, bufnr)
    -- Do things when language server attaches to
    -- the current buffer
end

for _, lsp in ipairs(servers) do
    nvim_lsp[lsp].setup {
        on_attach = on_attach
    }
end

The code above creates a new on_attach function and passes it to each server in our list of servers. But what to put in it?

The Keybindings and completion section of the lspconfig README illustrates adding some basic remaps that will work across every language server. Let’s add these:

-- lspconfig
local nvim_lsp = require('lspconfig')
local servers = { 'tsserver' }

local on_attach = function(client, bufnr)
  local function buf_set_keymap(...) vim.api.nvim_buf_set_keymap(bufnr, ...) end
  local opts = { noremap=true, silent=true }

  -- our first remap
  buf_set_keymap('n', 'gD', '<cmd>lua vim.lsp.buf.declaration()<CR>', opts)
end

for _, lsp in ipairs(servers) do
    nvim_lsp[lsp].setup {
        on_attach = on_attach
    }
end

This is a lot to digest. Let’s walk through it one step at a time.

We define a function named buf_set_keymap that accepts a variable number of arguments, denoted by the ….

buf_set_keymap is an abstraction over the vim.api.nvim_buf_set_keymap function.

We define a table named opts that holds some basic options for all of our remaps.

opts.noremap means “no recursive mapping”
opts.silent means the command will not be echoed in the command line

We call buf_set_keymap for the first time, passing in 4 parameters.
- 'n' tells LSP that this remap can run in NORMAL MODE
- 'gD' is the remap itself. The letters that you will type to perform some action.
- '<cmd>lua vim.lsp.buf.declaration()<CR>' is the actual command you want to perform. Without the remap, you would have to write this every time. <cmd> is like typing :. <CR> denotes a carriage return, such as hitting ENTER.
- opts is the options table we declared earlier

Our first remap is 'gD'. Typing it will be equivalent to typing :lua vim.lsp.buf.declaration() followed by ENTER. This remap will jump to the definition of the symbol under your cursor while in Neovim. It’s a really helpful remap that I use all the time.

Now that you have the basics down, let’s add the rest of the remaps defined in the lspconfig README:

-- lspconfig
local nvim_lsp = require('lspconfig')
local servers = { 'tsserver' }

local on_attach = function(client, bufnr)
    local function buf_set_keymap(...) vim.api.nvim_buf_set_keymap(bufnr, ...) end
    local opts = { noremap=true, silent=true }

    buf_set_keymap('n', 'gD', '<cmd>lua vim.lsp.buf.declaration()<CR>', opts)
    buf_set_keymap('n', 'gd', '<cmd>lua vim.lsp.buf.definition()<CR>', opts)
    buf_set_keymap('n', 'K', '<cmd>lua vim.lsp.buf.hover()<CR>', opts)
    buf_set_keymap('n', 'gi', '<cmd>lua vim.lsp.buf.implementation()<CR>', opts)
    buf_set_keymap('n', '<C-k>', '<cmd>lua vim.lsp.buf.signature_help()<CR>', opts)
    buf_set_keymap('n', '<space>wa', '<cmd>lua vim.lsp.buf.add_workspace_folder()<CR>', opts)
    buf_set_keymap('n', '<space>wr', '<cmd>lua vim.lsp.buf.remove_workspace_folder()<CR>', opts)
    buf_set_keymap('n', '<space>wl', '<cmd>lua print(vim.inspect(vim.lsp.buf.list_workspace_folders()))<CR>', opts)
    buf_set_keymap('n', '<space>D', '<cmd>lua vim.lsp.buf.type_definition()<CR>', opts)
    buf_set_keymap('n', '<space>rn', '<cmd>lua vim.lsp.buf.rename()<CR>', opts)
    buf_set_keymap('n', '<space>ca', '<cmd>lua vim.lsp.buf.code_action()<CR>', opts)
    buf_set_keymap('n', 'gr', '<cmd>lua vim.lsp.buf.references()<CR>', opts)
    buf_set_keymap('n', '<space>e', '<cmd>lua vim.lsp.diagnostic.show_line_diagnostics()<CR>', opts)
    buf_set_keymap('n', '[d', '<cmd>lua vim.lsp.diagnostic.goto_prev()<CR>', opts)
    buf_set_keymap('n', ']d', '<cmd>lua vim.lsp.diagnostic.goto_next()<CR>', opts)
    buf_set_keymap('n', '<space>q', '<cmd>lua vim.lsp.diagnostic.set_loclist()<CR>', opts)
    buf_set_keymap('n', '<space>f', '<cmd>lua vim.lsp.buf.formatting()<CR>', opts)
end

for _, lsp in ipairs(servers) do
    nvim_lsp[lsp].setup {
        on_attach = on_attach
    }
end

Now your language server(s) will be able to run these remaps whenever you please. There’s a lot here, and there’s a good chance you won’t use them all. But it’s helpful to have them in case you do. I like to keep my lsp.lua file close while I work, referencing these remaps in case I want to perform some actions. Here are a few that I like to use:

gD - see the declaration of a symbol (function, variable, etc.)
K - see some info about a symbol in a hover window
gr - show a list of references to a symbol
<space>e - show any issues on the current line

Once the rest of our remaps have been added to our on_attach function, let’s save the file and require it inside of init.lua:

require('YOUR_NAMESPACE/telescope')
require('YOUR_NAMESPACE/lightline')
require('YOUR_NAMESPACE/gitsigns')
require('YOUR_NAMESPACE/lsp')

To give your remaps a test drive, make sure to save and source this file. Hop into a project that utilizes one of your language servers and you’re all set! If you're not sure that LSP is working in a particular file, type the command :LspInfo.

You can read more about Neovim's built-in LSP using the command:

:h lsp

Autocompletion

Next on the list of language-related items to configure is autocompletion. Autocompletion is a huge productivity improvement for developers, and it does not come baked into Neovim. We need to install a few plugins to make it happen.

In our init.vim:

" ...general settings

call plug#begin('~/.config/nvim/plugged')

" ...plugins

" Autocompletion
Plug 'hrsh7th/nvim-cmp'
Plug 'hrsh7th/cmp-nvim-lsp'
Plug 'L3MON4D3/LuaSnip'
Plug 'saadparwaiz1/cmp_luasnip'
Plug 'onsails/lspkind-nvim'

call plug#end()

Yes we just installed 5 plugins for autocompletion. Don’t freak out. They each have their purpose:

nvim-cmp -The main plugin
cmp-nvim-lsp - A dependency of nvim-cmp
LuaSnip - Autocomplete your snippets.
cmp_luasnip - Snippet completion source. Not quite sure what it does? But it’s recommended in defaults.nvim.
lspkind-nvim - Autocompletion icons

Save, source and :PlugInstall.

Now that all of these plugins are installed, let’s glue them together. But, instead of configuring it within its own .lua file, we’ll want to colocate it with our LSP config. You'll see why.

Ino our lsp.lua file:

-- ...lspconfig

-- nvim-cmp
local cmp = require('cmp')
local lspkind = require('lspkind')
local luasnip = require('luasnip')

-- better autocompletion experience
vim.o.completeopt = 'menuone,noselect'

cmp.setup {
    -- Format the autocomplete menu
    formatting = {
        format = lspkind.cmp_format()
    },
    mapping = {
        -- Use Tab and shift-Tab to navigate autocomplete menu
        ['<Tab>'] = function(fallback)
            if cmp.visible() then
              cmp.select_next_item()
            elseif luasnip.expand_or_jumpable() then
              luasnip.expand_or_jump()
            else
              fallback()
            end
          end,
        ['<S-Tab>'] = function(fallback)
            if cmp.visible() then
              cmp.select_prev_item()
            elseif luasnip.jumpable(-1) then
              luasnip.jump(-1)
            else
              fallback()
            end
        end,
        ['<CR>'] = cmp.mapping.confirm {
            behavior = cmp.ConfirmBehavior.Replace,
            select = true,
        },
    },
    snippet = {
        expand = function(args)
            luasnip.lsp_expand(args.body)
        end
    },
    sources = {
        { name = 'nvim_lsp' },
        { name = 'luasnip' },
    },
}

A lot to take in. Let’s walk it out.

formatting.format - Formats the autocomplete menu using lspkind, a plugin we installed earlier. This adds icons to keywords and variables to autocomplete options.
mapping - Custom keybindings for better autocomplete menu navigation. Press <Tab> to navigate forward, and <Shift-Tab> to navigate backwards. Press <CR> (Enter) to confirm selection.
snippet - Enables snippet autocompletion via LuaSnip
sources - Declare autocompletion sources.

After configuring the autocompletion plugins, we need to wire it all up with our language servers:

-- lspconfig
local on_attach = function(client, bufnr)
  -- ...
end

local capabilities = vim.lsp.protocol.make_client_capabilities()
capabilities = require('cmp_nvim_lsp').update_capabilities(capabilities)

local servers = { 'tsserver' }
for _, lsp in ipairs(servers) do
    nvim_lsp[lsp].setup {
        capabilities = capabilities,
        on_attach = on_attach,
    }
end

-- ...nvim-cmp

The above code adds a new property named capabilities to each language server. All together, lsp.lua now looks like this:

-- lspconfig
local nvim_lsp = require('lspconfig')
local servers = { 'tsserver' }

local on_attach = function(client, bufnr)
    local function buf_set_keymap(...) vim.api.nvim_buf_set_keymap(bufnr, ...) end
    local opts = { noremap=true, silent=true }

    buf_set_keymap('n', 'gD', '<cmd>lua vim.lsp.buf.declaration()<CR>', opts)
    buf_set_keymap('n', 'gd', '<cmd>lua vim.lsp.buf.definition()<CR>', opts)
    buf_set_keymap('n', 'K', '<cmd>lua vim.lsp.buf.hover()<CR>', opts)
    buf_set_keymap('n', 'gi', '<cmd>lua vim.lsp.buf.implementation()<CR>', opts)
    buf_set_keymap('n', '<C-k>', '<cmd>lua vim.lsp.buf.signature_help()<CR>', opts)
    buf_set_keymap('n', '<space>wa', '<cmd>lua vim.lsp.buf.add_workspace_folder()<CR>', opts)
    buf_set_keymap('n', '<space>wr', '<cmd>lua vim.lsp.buf.remove_workspace_folder()<CR>', opts)
    buf_set_keymap('n', '<space>wl', '<cmd>lua print(vim.inspect(vim.lsp.buf.list_workspace_folders()))<CR>', opts)
    buf_set_keymap('n', '<space>D', '<cmd>lua vim.lsp.buf.type_definition()<CR>', opts)
    buf_set_keymap('n', '<space>rn', '<cmd>lua vim.lsp.buf.rename()<CR>', opts)
    buf_set_keymap('n', '<space>ca', '<cmd>lua vim.lsp.buf.code_action()<CR>', opts)
    buf_set_keymap('n', 'gr', '<cmd>lua vim.lsp.buf.references()<CR>', opts)
    buf_set_keymap('n', '<space>e', '<cmd>lua vim.lsp.diagnostic.show_line_diagnostics()<CR>', opts)
    buf_set_keymap('n', '[d', '<cmd>lua vim.lsp.diagnostic.goto_prev()<CR>', opts)
    buf_set_keymap('n', ']d', '<cmd>lua vim.lsp.diagnostic.goto_next()<CR>', opts)
    buf_set_keymap('n', '<space>q', '<cmd>lua vim.lsp.diagnostic.set_loclist()<CR>', opts)
    buf_set_keymap('n', '<space>f', '<cmd>lua vim.lsp.buf.formatting()<CR>', opts)
end

local capabilities = vim.lsp.protocol.make_client_capabilities()
capabilities = require('cmp_nvim_lsp').update_capabilities(capabilities)

local servers = { 'tsserver' }
for _, lsp in ipairs(servers) do
    nvim_lsp[lsp].setup {
        capabilities = capabilities,
        on_attach = on_attach,
    }
end

-- nvim-cmp
local cmp = require('cmp')
local lspkind = require('lspkind')
local luasnip = require('luasnip')

-- better autocompletion experience
vim.o.completeopt = 'menuone,noselect'

cmp.setup {
    -- Format the autocomplete menu
    formatting = {
        format = lspkind.cmp_format()
    },
    mapping = {
        -- Use Tab and shift-Tab to navigate autocomplete menu
        ['<Tab>'] = function(fallback)
            if cmp.visible() then
              cmp.select_next_item()
            elseif luasnip.expand_or_jumpable() then
              luasnip.expand_or_jump()
            else
              fallback()
            end
          end,
        ['<S-Tab>'] = function(fallback)
            if cmp.visible() then
              cmp.select_prev_item()
            elseif luasnip.jumpable(-1) then
              luasnip.jump(-1)
            else
              fallback()
            end
        end,
        ['<CR>'] = cmp.mapping.confirm {
            behavior = cmp.ConfirmBehavior.Replace,
            select = true,
        },
    },
    snippet = {
        expand = function(args)
            luasnip.lsp_expand(args.body)
        end
    },
    sources = {
        { name = 'nvim_lsp' },
        { name = 'luasnip' },
    },
}

Treesitter

The last plugin to improve Neovim's language support is treesitter. We will be installing it for improved syntax highlighting. In your init.vim, add the following to you list of declared plugins:

" ...general settings

call plug#begin('~/.config/nvim/plugged')

" ...plugins

" Treesitter
Plug 'nvim-treesitter/nvim-treesitter', { 'do': ':TSUpdate' }

call plug#end()

Next, create a treesitter.lua file in your namespace directory:

nvim ~/.config/nvim/lua/YOUR_NAMESPACE/treesitter.lua

Inside this file we'll add the following:

local treesitter = require('nvim-treesitter.configs')

treesitter.setup {
    highlight = {
        enable = true
    }
}

Finally, update your init.lua to include treesitter.lua:

require('YOUR_NAMESPACE/telescope')
require('YOUR_NAMESPACE/lightline')
require('YOUR_NAMESPACE/gitsigns')
require('YOUR_NAMESPACE/lsp')
require('YOUR_NAMESPACE/treesitter')

And that's it! Source your init.vim and you should see an improved syntax highlighting experience.

Remaps

The following will not be a tutorial on remaps themselves, as remaps in Vim are a topic worthy of a separate article. There are also plenty of great resources on the topic:

Instead, I will quickly explain what they are and why you would want to use them, and ultimately hope to inspire you to seek out your own.

Let's begin.

Over the course of this article, we've covered many plugins that introduce their own commands:

" Telescope
:Telescope find_files
:Telescope buffers
:Telescope live_grep

" vim-fugitive
:Git
:Git add
:Git status
:Git blame

" lspconfig
:LspInfo

On top of these plugin-specific commands, Vim has its own set of commands. It can be cumbersome to type out the entire command every time you want to use it. Instead, you can "map" these commands to a pattern of keystrokes. These are remaps.

I declare my remaps inside init.vim. Here's an example of one of my favorites:

" ...general settings

" ...plugins

" remaps
nnoremap <C-p> :Telescope find_files<Cr>

The remap above is <C-p>, or CTRL+p. Each time I type this pattern, the command :Telescope find_files<Cr> will run. <Cr> must be explicitly declared in order for the command to be "entered", i.e - with <Enter>.

Here are a few others:

" ...general settings

" ...plugins

" remaps
let mapleader = ' '

nnoremap <leader>h :wincmd h<Cr>
nnoremap <leader>j :wincmd j<Cr>
nnoremap <leader>k :wincmd k<Cr>
nnoremap <leader>l :wincmd l<Cr>

nnoremap <C-p> :Telescope find_files<Cr>

A mapleader is a special character you can appoint to "lead" your remaps. This both simplifies remap keystrokes and prevents unwanted remap collisions. It defaults to \, but here I'm setting it to an empty space, ' '.

<leader>h is equivalent to typing the <Space> bar followed by the letter h. Doing so will run the command :wincmd h<Cr>.

I believe remaps are one of those things you'll undoubtedly look for as you notice pain points in your own workflow. It can be helpful to puruse others' Vim configurations and see what they use for inspiration.

Tips and tricks

Use relative line numbers

Your Neovim terminal supports line numbers with the following setting:

set number

When you get more advanced with your Vim movements, you'll look for ways to move vertically faster. One of the ways to do this is to explicitly type the line number you want to go to. This is easier with relative line numbers:

set number
set relativenumber

How does it work? The line your cursor is currently on will be denoted "line 0". The rest of the lines above and below will be numbered relative to their distance from line 0. For example, the line directly below your cursor will be line 1. So will the line directly above. To jump to line 1 below, type the number 1 plus the letter j. To go to line 1 above, type the number 1 plus the letter k.

Alias the nvim command

An alias is a shortcut defined in your terminal shell’s settings that allows you to run regular commands with custom names. An example alias that many people use is:

alias gc="git checkout"

Instead of typing git checkout every time I want to check out a branch, I just need to type gc. My terminal knows that when I enter gc, what I really mean is git checkout.

Defining your aliases is dependent on which terminal shell you are using. There are a number of shells that people use these days, like bash, zsh and fish. I use zsh, but you may not be. If you don’t know what shell you are using, you can run the following command in your terminal:

echo $SHELL

Aliases are defined in your shell’s configuration file. For bash users, that would be .bashrc. For zsh users, .zshrc. etc. etc. Your mileage may vary. Locate your specific file, and add the following:

alias vim ="nvim"

Now anytime you run the command vim, you will really be running the command nvim. If you still want access to the original vim command, you can prefix it with a \ character:

\vim

The command above will use the unaliased vim command. The more you know, right?

Save your Neovim configuration in Git

This is a major key! I've written a blog post on this very topic. I suggest you take a look. Your Neovim configuration is a subset of a larger group of configuration files dubbed "dotfiles". Dotfiles are the life blood of a good development environment. Make sure you keep yours portable!

Experiment!

Programming is way more fun when you're being efficient. Neovim can get you there over time, but you have to be willing to try new things. New plugins, new remaps, etc.

Keep an eye on the community

Neovim has an active subreddit and forum. These are great places to learn and find new plugins to experiment with.

Conclusion

Phew! If you've stuck with me to the end, I appreciate you! This was a massive article, one of the biggest I've ever written. We discussed settings, plugins, color schemes, language support, autocompletion and remaps. I hope you learned something!

If you're curious to see my configuration, you can checkout my dotfiles on GitHub, specifically the nvim directory. And if you're just getting started on your Vim journey, please let me know! It's been a challenging and exciting one for me, and I'm only getting started.

Manage Your Dotfiles Like a Superhero

Jake Wiesler — Mon, 20 Sep 2021 21:01:04 +0000

I'm going to assume you are reading this because:

you have one or more dotfiles lying around and you don't know how to organize them.
you heard that you can save dotfiles for later use in case your computer explodes or something.
you've seen other people's dotfiles on GitHub, and they look so damn cool.
you like superheros.

The thing about programming, or anything you try to teach yourself for that matter, is that when you start, you don't know what you don't know.

Dotfiles are a perfect example. You don't know about them until either someone tells you they are thing, or you fall down a rabbit hole and find yourself setting the $PATH variable in your .bashrc.

Eventually you go from not knowing about dotfiles, to really caring about them. You realize just how essential they are for your workflow. How having a good relationship with them can accelerate your ability to solve problems.

And most important, you realize just how picky you really are, and how your dotfiles are a perfect outlet for such pickiness.

What you're probably doing

If you are not managing your dotfiles in any way, then they are probably strewn about your home directory. You probably have a file for your shell, say a .bashrc or a .zshrc. You probably have a .vimrc or something like that. You might even have a .gitconfig.

In this scenario your dotfiles are ephemeral. They exist as long as your machine exists. And when your machine goes down for the long nap, so will your dotfiles. You don't want to be that girl or guy setting up a new machine from scratch every single time. It sucks. I've been there. Avoid at all costs!

What you should be doing

Your dotfiles should be stored in such a way that you can access them anywhere at any time. If something happens to your current machine, or you need to setup another one, you're a git clone away from an identical development environment. That is the dream.

You may have come across resources like Atlassian's How to store dotfiles, or Yet Another Dotfiles Manager. I've tried them both. They work, but they're a little involved.

Instead I recommend you use GNU Stow, a utility that lets you symlink files from different parts of your machine and make them appear as if they are installed in the same place. This will make sense soon.

How to do it

Step one is to create a .dotfiles directory in your home directory. For example, let's say Alice's home directory is:

/Users/alice

Alice will create her .dotfiles directory here:

mkdir /Users/alice/.dotfiles

Next, you'll need to get your hands on the stow package. Luckily it is a pretty ubiquitous piece of software, so most package managers should make it available to you. For MacOS users you can use homebrew:

brew install stow

The third step is to move existing dotfiles to the .dotfiles directory, and/or create new ones depending on your scenario. This step requires some explanation of how stow works.

Understanding `stow`

stow has a few key concepts that, when understood, should make this entire process a breeze. These concepts can be found in the Terminology documentation:

A package is a folder containing related dotfiles.
A stow directory is a folder containing one or more packages.
A target directory is the location in which a package's contents will be symlinked.

What this will look like in practice is:

target-directory
├── stow-directory
│   ├── package-1
│   │   └── .dotfile-1
│   ├── package-2
│   │   └── .dotfile-2
│       └── .dotfile-3

Let's use Alice again as an example. Alice's .dotfiles directory is located at:

/Users/alice/.dotfiles

The .dotfiles directory is her stow directory. Currently it's empty. She will need to create one or more packages within it to house her dotfiles.

Alice has the following dotfiles:

.bashrc
.vimrc
.gitconfig

Since each file belongs to a different "package", bash, vim and git respectively, Alice will create a package for each:

# /Users/alice/.dotfiles 

mkdir bash
mkdir vim
mkdir git

Now, Alice can move each dotfile into their respective package directory. As a result, the .dotfiles directory will look like this:

.dotfiles
├── bash
│   └── .bashrc
├── vim
│   └── .vimrc
└── git
    └── .gitconfig

.dotfiles is the stow directory. bash, vim and git are package directories. Their contents are the dotfiles themselves. Now, all that's left is to use the stow command to target each package inside of the stow directory:

# /Users/alice/.dotfiles 

stow bash
stow vim
stow git

The commands above will symlink the contents of each package to the target directory.

But what is the target directory?

With stow, the target directory is one directory above the stow directory. In Alice's case, if her stow directory is:

/Users/alice/.dotfiles

Then her target directory is:

/Users/alice

Let me explain these symlinks a little bit better. When you run stow <package>, the stow utility will create the least amount of symlinks necessary to mirror the contents of the package to your target directory. If your package had a single dotfile, stow will create a single symlink:

/Users/alice
├── .dotfiles
│   ├── vim
│   │   └── .vimrc
├── .vimrc -> .dotfiles/vim/.vimrc

The arrow (->) represents a symlinked file pointing to its original source.

This might seem obvious to some, but what happens if you have a subfolder within a package? For instance, it's common for Vim users to not only have a .vimrc file in their home directory, but also a .vim directory with scripts and plugins. How would you stow that?

/Users/alice
├── .dotfiles
│   ├── vim
│       └── .vimrc
│       └── .vim
|           └── script.vim
├── .vimrc -> .dotfiles/vim/.vimrc
├── .vim   -> .dotfiles/vim/.vim
|   └── script.vim

This gives you a ton of flexibilty, because very often command line tools like git and vim use more than dotfiles stored in the home directory. They have their own directories and subdirectories, and being able to model this out within a package is really powerful.

Once you can visualize how stow mirrors a package's contents to the target directory, structuring your .dotfiles directory will be easy peezy lemon squeezy.

One more example

The last example I'll give should really drive stow symlinks home. Let's say Alice is a vim user, but instead of traditional vim she uses Neovim. Neovim doesn't use a .vimrc file in her home directory, but instead an init.vim file which is located at:

/Users/alice/.config/nvim/init.vim

The init.vim file is heavily nested. If Alice wants to stow this, how would she do it?

It's pretty simple actually. In her .dotfiles directory she creates a package called nvim. It would look like this:

.dotfiles
├── nvim
│   ├── .config
│       └── nvim
|           └── init.vim

The folder structure starting from .dotfiles/nvim is the same structure that is expected in Alice's home directory. Now she just needs to stow the nvim directory:

# /Users/alice/.dotfiles 

stow nvim

And the result will be:

/Users/alice
├── .dotfiles
│   ├── nvim
│       └── .config
|           └── nvim
|               └── init.vim
├── .config -> .dotfiles/nvim/.config

Storing dotfiles in git

The .dotfiles directory is just like any old directory on your machine. You can git init and git push up to your git repository of choice:

# /path/to/your/.dotfiles

git init
git add .
git commit -m "storing initial dotfiles"
git push

You can add a .gitignore file to prevent unwanted configs from being pushed to your remote repository, and a README to illustrate how it all works.

Conclusion

I hope this has helped you gain a better understanding of how to manage your dotfiles. This is by no means the only way to do it, but it is my preferred way.

You can really take this as far as you want to go. For instance, I am planning on creating an install script that can be run on new machines. This script will install a bunch of dependencies like node and the like, stow my dotfiles so the symlinks are created, etc.

If you want to take a peak at my dotfiles, you can see them here. They're still a work in progress, but it should be a good resource for learning.

If you made it to the end, thanks for reading! Have questions? See a mistake? Just want to say hi? Reach out to me on Twitter.

The Next Iteration of the Web

Jake Wiesler — Mon, 13 Sep 2021 10:27:00 +0000

The following is a post from my newsletter, Original Copy. Want early access to posts like this? Subscribe here.

Tim Berners-Lee is best known for inventing the World Wide Web. In 1989, while working at CERN, he proposed an idea: "a web of hypertext documents viewable by browsers".

You can see the appeal of such a technology. An industry ripe with innovation and experimentation requires rapid knowledge transfer. The idea was so powerful that a few years later it extended to the general public. The Internet was born.

This first iteration of the Web, dubbed Web 1.0, lasted from the early 90s until about 2004. It was all about consuming static content, usually in the form of texts, links and images. Creators of this content were the "webmasters" who knew how to publish on the Web. An uncommon skill.

Web 2.0

Today we experience an interactive and social Web. Anyone can create and publish content with the click of a button. No webmaster needed. This is Web 2.0, the modern Web.

Personal computers and smart phones led the way. Tech giants like Google and Facebook followed. The applications created by these companies empower users to learn, shared and build. They grew faster than the open protocols created during the Web 1.0 era. A massive improvement, but not without consequences.

Web 2.0 is a centralized Web. Applications are owned by a single entity or corporation. Within centralized applications, the owner is the single source of truth. They make the rules, and you play the game.

The owner has control of everything:

Permissions
Governance
Data
Equity

This has lead to issues of censorship, security and the topic that intrigues me the most: privacy.

Data wars

In 1973, the artist Richard Serra coined the phrase, "If something is free, you're the product." At the time he was referring to television. His point was that television was the audience. Its main purpose was to shuttle viewers to an advertiser. A funnel.

Today's most popular Internet applications, Google, Facebook, Twitter etc., act the same way. They're all free to use, yet they are among the richest companies in the United States. At the time of writing this, Google and Facebook are in the top 5 companies in the US by market capitalization. And their product is free!

The modern Web empowers companies to give away their technology at no cost. This removes barriers to entry so users can pile in. The company's only goal is to get you in and keep you in as long as possible, because you have something they need:

A pair of eyeballs.

The more users they acquire, the more data they collect and the more money they make off of advertising. This is THE playbook used by technology companies all over the world. Why? Because it works! It works so well that you and I, aware of this madness, continue to "use".

Enter Web 3.0

I was too young to recognize the dramatic shift from Web 1.0 to Web 2.0. One day you wake up, and MySpace exists. Everyone's talking about it. Everyone's using it. It happened fast!

Now that I'm older, and I've been in this Web Development racket for almost a decade, I have my ear closer to the ground. I sense the paradigm shifting again.

Web 3.0, the rapidly approaching (pssssst! It's already here) next iteration of the Web, is a decentralized Web. It aims to flip the system on its head, turning the keys over to the participants of the network (the users).

Web 3.0 applications are usually referred to as Decentralized applications or Dapps. They are not owned by a single entity. They are not deployed to a centralized server. Rather, they're isolated pieces of code deployed to a peer-to-peer network: a blockchain.

The validity of the blockchain and its app ecosystem is upheld through incentives. These incentives take the form of digital tokens - Cryptocurrency. Awarded to participants on the network through various "tokenomics".

The use of these tokens is where things get interesting. The most basic function is paying for actions taken on the network. Any action that effect's the "state" of the blockchain costs money - a transaction. And that's only scratching the surface.

Anyone can use a decentralized app. Logins are anonymous. Payments are built-in, anonymous and backed by cryptography.

The early adopters

With all the buzz around Web 3.0, it is still early days.

Certain use cases still rely on some layer of centralization. Centralization makes things easier to coordinate. Achieving full decentralization introduces difficult problems like communication, incentives and consensus. But they are problems worth solving.

There is a mass migration of smart engineers and designers heading to the Wild West of Web 3.0. I am excited for its future.

Most of my work is still in Web 2.0 land, but I'm ramping up on Web 3.0 technology. A lot of the content I'll be sharing will focus on it.

Build a JAMStack Blog with NextJS and Ghost

Jake Wiesler — Thu, 26 Aug 2021 14:09:41 +0000

I have a certain affinity for Ghost, an open-source publishing platform created in 2013 and built on NodeJS. It was the first platform I used to build my website back in 2015, but over time curiosity struck and I moved away from it.

Now, in 2021, I'm revisiting my old friend again. Why? It's latest release, version 4, brings some awesome new features:

A revamped Dashboard
Native support for Newsletters
Paid subscriptions
Tons of integrations
A cheaper Ghost(Pro) starter plan

It's a huge update, and I'm a sucker for brand redesigns. However, since 2015 I've acquired the skills to build a site without needing to rely on tools like Ghost, so why go back?

The beauty of Ghost

Personal publishing and gated content as a business continues to increase in popularity, and Ghost is well positioned in this space. The new Members feature gives creators a way to monetize their work with very little effort on the administrative side.

Managing content is a real pleasure. You can write posts, schedule them for publishing and send them straight to the inbox of your members. You can mark some posts as free and others as paid, providing a way for your audience to fund your work.

And all of this is controlled from a clean Dashboard. It's a really great way to manage your content. Much better than writing in markdown files.

My issues with Ghost

Customization. I want full control of how my site looks and feels. In reality, Ghost does not stop you from having this level of power. The platform has a rich theme ecosystem, with paid and free themes available to all. However, if you want to build a theme of your own you have to do it in handlebars.

I'll pass.

Another is performance. Ghost is pretty fast and comes with a lot of niceties out of the box (SEO for one), but it's not fast enough for me. I want blazing fast, and I have the skills to do that on my own.

Enter the JAMStack

The good news is that Ghost is front-end agnostic, meaning you can "bring your own" front-end. Manage content in Ghost, and query for it using their APIs. A Headless CMS.

Headless because the CMS has no dedicated front-end. You can plop whichever one you want on top, and the CMS will abide. It's a beautiful thing really, and gets us to the foundation of JAMStack.

JavaScript - build your front-end with a modern JavaScript framework.
APIs - Query for your content with Ghost's APIs
Markup - Write your content as markup in Ghost

In this post we'll use NextJS as our front-end framework of choice. With NextJS, we can build a blazing fast front-end and query Ghost for our content.

It's the best of both worlds. Keep the Dashboard and Editor on Ghost's side, and the performance and developer experience on NextJS's side.

Installing Ghost

The first thing we need to do is install Ghost on our development machine. Open a terminal and install the latest version of ghost-cli globally using your package manager of choice. I am a yarn man.

yarn add ghost-cli@latest

It's important to note that your version of node matters. I've run into issues in the past when being on some of the latest versions. At time of writing this, Ghost recommends v14 of node, their long term support version.

Next we'll run a few terminal commands to create a directory and install a ghost instance:

mkdir ghost-development

cd ghost-development

ghost install local

The first two commands are self-explanatory. The name of your directory does not matter. The third command, ghost install local, runs a number of scripts and sets you up with a local installation of Ghost hosted at a local url. Usually this url is http://localhost:2368. If you navigate to it in your browser of choice, what you'll see is Casper, the default Ghost theme.

If you go to http://localhost:2368/ghost, you'll hit the admin side of Ghost. This will require you to create an account. It's not going to be a live account, just a local one that will let you interface with the admin side for development 🐳.

Put in whatever data you want, skip the staff users section and boom. You're logged in.

Installing NextJS

Now that we have Ghost up and running locally, we'll setup our front-end. In a separate directory, bootstrap a NextJS app. Again, with yarn:

yarn create next-app my-next-front-end

This will set you up with a NextJS project in the my-next-front-end directory. That's it!

Querying for blog posts

When you start up a Ghost site for the first time, the theme will deploy with some "Getting Started" posts. This is adequate for our purpose. No need to create more. I mean, you can if you want. Do you.

Eventually we'll need to fetch those blog posts. Ghost has two APIs, the Content API and the Admin API. For a list of blog posts we'll need to interface with the Content API.

Ghost also provides a few API clients to make things easy. Let's install the client for the Content API. In your NextJS app directory run the following command:

yarn add @tryghost/content-api

If you're interested, here is the documentation for the @tryghost/content-api.

Now that we have our dependency installed, we'll write some logic to fetch a list of blog posts. I like to put this sort of logic in a lib directory:

mkdir lib

Of course you can also create the folder in your text editor, but we're terminal first here.

In our lib directory we'll create a ghost.js file to keep it simple:

cd lib
touch ghost.js

Alright now we're cooking. Let's open up ghost.js and import @tryghost/content-api:

import GhostContentAPI from '@tryghost/content-api';

In order to start using the client we'll need to initiate it:

import GhostContentAPI from '@tryghost/content-api';

const api = new GhostContentAPI({
  url: '',
  key: '',
  version: ''
});

I've left the 3 configuration properties empty for a reason. They each need explanation:

`url` and `key`

Both the url and key values will be different in a development and production environment. We are only concerned with the development environment for now. Navigate to the local instance of your Ghost admin (http://localhost:2368/ghost) in the browser. On the left hand side you should see an "Integrations" section. Click it. We will need to create a new custom integration to get these values.

Click the "Add Custom Integration" button. Name the integration whatever you want. I'm calling it "NextJS Front-end". Click "Create", and you should then see a few values. The ones you want are the "Content API Key" and the "API URL". These will be your development url and key values. Remember, in production they will be different.

`version`

At time of writing, this is the 3rd version of the Ghost API, though they also support a canary value. Let's be safe and use 'v3'.

Our final configuration should look like this:

import GhostContentAPI from '@tryghost/content-api';

const api = new GhostContentAPI({
  url: '<YOUR_API_URL>',
  key: '<YOUR_CONTENT_API_KEY>',
  version: 'v3'
});

Instead of hardcoding the url and key values, lets make it environment-agnostic. Create a .env.local file at the root of your NextJS application, and inside add the two values:

GHOST_API_URL=<YOUR_API_URL>
GHOST_CONTENT_API_KEY=<YOUR_CONTENT_API_KEY>

And in our ghost.js file we can update our config to the following:

import GhostContentAPI from '@tryghost/content-api';

const api = new GhostContentAPI({
  url: process.env.GHOST_API_URL,
  key: process.env.GHOST_CONTENT_API_KEY,
  version: 'v3'
});

This works out really well, because in development we can use our local instance of Ghost, but in production we can use the production instance. Just so long as you make sure to supply the correct values to these environment variables when deploying to production. But more on that later.

Now that we are configured, lets right a function that fetches a list of all blog posts from Ghost:

export async function getAllPosts() {
  const posts = await api.posts.browse({ limit: 'all' });
  return posts;
}

Easy peezy lemon squeezy.

Render a list of blog posts

Now that we have our function to fetch a list of posts, lets use it to render them on our homepage. In your pages/index.js file, remove the bootstrapped code and replace with the following:

import Link from 'next/link'
import { getAllPosts } from '../lib/ghost';

export async function getStaticProps() {
  const posts = await getAllPosts();
  return { props: { posts } };
}

export default function Home({ posts }) {
  return (
     <ul>
      {posts.map((post) => (
        <li key={post.uuid}>
          <Link href={`/${post.slug}`}>
            <a>{post.title}</a>
          </Link>
        </li>
      ))}
    </ul>
  );
}

The getStaticProps function is a special function in NextJS that lets us fetch data at build time. What this means is we can fetch our list of posts once, when we build our project, and generate a static html document that renders them.

Using our getAllPosts function from lib/ghost.js, our posts will be fetched and supplied to the Home page component as the posts prop. Inside of our render tree we display the title of each post as a NextJS Link. For a list of all available values on a post coming from Ghost (hey that rhymes), see here.

Creating pages for each post

We might have hundreds of blog posts to render on our site, and we can't possibly be burdened to predefine all of their routes. But, we know that every post has an associated slug value. We can use this to our advantage.

In the pages directory, lets create a new file called [slug].js. These are known as dynamic routes in NextJS, and they are an awesome feature. Think of this page as a "catch all". The slug will be used as the parameter that lets us dynamically render content based on its value.

To do this, we'll need to utilize another special function in NextJS called getStaticPaths. Here's how it works:

import { getAllPosts } from '../lib/ghost'

export async function getStaticPaths() {
  const posts = await getAllPosts();
  const paths = posts.map(({ slug }) => ({ params: { slug } }));
  return { paths, fallback: false };
}

getStaticPaths is the mechanism by which we statically generate dynamic routes. We fetch all the blog posts from Ghost at build time, map through each and pull out their slug value. The slug will be given to each page as a unique parameter, and we can use it to fetch the content for the corresponding blog post.

If this is confusing, consider the following example. If you had only one blog post in your Ghost instance, and that post had the slug /my-happy-slug, then a page will be created at the route yoursite.com/my-happy-slug.

Rendering post content

Now that we can generate a page for every post, we'll need to render some content. In order to accomplish this, we'll need to create a new function in our lib/ghost.js file called getPostBySlug:

export async function getPostBySlug(slug) {
  const post = await api.posts.read(
    { slug },
    { formats: ['html'] }
  );
  return post
}

This function accepts the slug of a post and returns the post's data, making sure to include the post's content in html format. If you're curious to see what a post object returned from Ghost looks like, you can refer to the documentation again.

Let's use this function in our [slug].js page to fetch post content:

import { getAllPosts, getPostBySlug } from '../lib/ghost';

export async function getStaticPaths() {
  const posts = await getAllPosts();
  const paths = posts.map(({ slug }) => ({ params: { slug } }));
  return { paths, fallback: false };
}

export async function getStaticProps({ params }) {
  const { slug } = params;
  const data = await getPostBySlug(slug);
  return { props: { data } };
}

When each page is built, the getStaticProps function is called. As an argument, getStaticProps receives the page's params object. Inside of this object we can gain access to the page's slug value. Now, getting the page's data is trivial. We call getPostBySlug, pass the slug value, and the returned data representing our post can be passed to our page's component as the data prop:

import { getAllPosts, getPostBySlug } from '../lib/ghost';

export async function getStaticPaths() {
  const posts = await getAllPosts();
  const paths = posts.map(({ slug }) => ({ params: { slug } }));
  return { paths, fallback: false };
}

export async function getStaticProps({ params }) {
  const { slug } = params;
  const data = await getPostBySlug(slug);
  return { props: { data } };
}

export default function Post({ data }) {
  return (
    <article>
      <h1>{data.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: data.html }} />
    </article>
  );
}

Rendering post tags

One feature that comes baked-in with most Ghost themes is this concept of tags. It is a way to categorize your content. #Programming, #Health, #Bitcoin, etc. These are examples of tags that you can attach to each post you write. This may not be a feature you care to support, but some people might, so I'll include a section on how to achieve it.

Attaching a tag to your post inside of the Ghost editor should be self-explanatory. When you query for a blog post, you can add an option to include that post's tags in the returned data. Let's update getPostBySlug to do just that:

export async function getPostBySlug(slug) {
  return api.posts.read(
    { slug },
    { formats: ['html'], include: 'tags' }
  );
}

Now, every post will have access to its tags. Render them however you'd like:

export default function Post({ data }) {
  return (
    <article className={styles.article}>
      <h1>{data.title}</h1>
      <div>
        {data.tags.map((tag) => (
          <span key={tag.id}>#{tag.name}</span>
        ))}
      </div>
      <hr />
      <div dangerouslySetInnerHTML={{ __html: data.html }} />
    </article>
  );
}

For a list of all available properties on the tag object, see here.

If you want your readers to be able to click these tags to see a list of all posts tagged with this specific tag, you'll need to do a bit more work. First, lets change the span element above to a NextJS Link component:

import Link from 'next/link'

// ...

{data.tags.map((tag) => (
  <Link key={tag.id} href={`/tag/${tag.slug}`}>
    <a>#{tag.name}</a>
  </Link>
))}

Next, we'll need to dynamically generate a page that will render at the route /tag/[slug]. This is a similar process to how we generated dynamic pages for our blog posts.

First let's create a function called getAllTags inside of lib/ghost.js that will fetch all available tags:

export async function getAllTags() {
  const tags = await api.tags.browse({ limit: 'all' });
  return tags;
}

Next, In your pages directory, create a subdirectory called tag, and inside of it create a file called [slug].js. This page is going to be responsible for rendering a list of posts that are tagged with a specific tag name.

For example, if you had 4 posts tagged #React in Ghost, then a route called yoursite.com/tag/react will be created, and the page will render a list of those 4 posts.

import { getAllTags } from '../../lib/ghost';

export async function getStaticPaths() {
  const tags = await getAllTags();
  const paths = tags.map(({ slug }) => ({ params: { slug } }));
  return { paths, fallback: false };
}

The above code will handle dynamic generation of each tag's page, but we still need to render some content. Let's create a new function inside of lib/ghost.js file called getAllPostsByTagSlug that will help us with this:

export async function getAllPostsByTagSlug(slug) {
  const posts = await api.posts.browse({
    limit: 'all',
    filter: `tag:${slug}`
  });
  return posts;
}

This function will return all the posts that are tagged with a tag represented by its corresponding slug. Let's use this in our pages/tag/[slug].js file:

import { getAllTags, getAllPostsByTagSlug } from '../../lib/ghost';

export async function getStaticPaths() {
  const tags = await getAllTags();
  const paths = tags.map(({ slug }) => ({ params: { slug } }));
  return { paths, fallback: false };
}

export async function getStaticProps({ params }) {
  const { slug } = params;
  const posts = await getAllPostsByTagSlug(slug);
  return { props: { posts } };
}

Let's step through what's happening here. For every tag we have in our Ghost content, we are going to generate a corresponding page. Each page will fetch a list of all posts that are tagged with that specific tag. So the tag #Programming will have its own page at yoursite.com/tag/programming, and you will be able to see a list of all your posts that are tagged with #Programming. Pretty sweet!

The one thing we haven't addressed is that, even though you can see all the posts for a particular tag, you don't actually no what tag the page is representing unless you look at the url. Let's add one more function called getTagBySlug to our lib/ghost.js file:

export async function getTagBySlug(slug) {
  const tag = await api.tags.read(
    { slug },
    { include: 'count.posts' }
  );
  return tag
}}

Now we can call this function inside of getStaticProps to fetch some meta information about the tag itself:

import {
  getAllTags,
  getAllPostsByTagSlug,
  getTagBySlug
} from '../../lib/ghost';

export async function getStaticPaths() {
  const tags = await getAllTags();
  const paths = tags.map(({ slug }) => ({ params: { slug } }));
  return { paths, fallback: false };
}

export async function getStaticProps({ params }) {
  const { slug } = params;
  const posts = await getAllPostsByTagSlug(slug);
  const tagData = await getTagBySlug(slug);
  return { props: { posts, tagData } };
}

Now lets create the component that will render all of this information:

export default function Tag({ posts, tagData }) {
  return (
    <div>
      <h1>{tagData.name}</h1>
      <p>A collection of {tagData.count.posts} posts</p>
      <ul>
        {posts.map(post => /* render posts here */)}
      </ul>
    </div>
  )
}

And the full file will look like this:

import {
  getAllTags,
  getAllPostsByTagSlug,
  getTagBySlug
} from '../../lib/ghost';

export async function getStaticPaths() {
  const tags = await getAllTags();
  const paths = tags.map(({ slug }) => ({ params: { slug } }));
  return { paths, fallback: false };
}

export async function getStaticProps({ params }) {
  const { slug } = params;
  const posts = await getAllPostsByTagSlug(slug);
  const tagData = await getTagBySlug(slug)
  return { props: { posts, tagData } };
}

export default function Tag({ posts, tagData }) {
  return (
    <div>
      <h1>{tagData.name}</h1>
      <p>A collection of {tagData.count.posts} posts</p>
      <ul>
        {posts.map(post => /* render posts here */)}
      </ul>
    </div>
  )
}

And that's it! If you followed closely you should have a simple NextJS-powered blog using Ghost as a headless CMS. I kept it lean and basic, so that you can build upon this over time. If you are interested in the full example, there is a GitHub repository here. Feel free to clone, fork and go wild.

Deploying to production

The last step in this journey is getting your site in production. This involves two separate applications: your CMS (Ghost), and your front-end (NextJS).

Deploying NextJS to production is actually a breeze if you use Vercel, the company behind the framework. They have a generous free tier, and all you have to do is hook up your GitHub repository and click a few buttons. It's painless really. They have great documentation, and setting up your environment variables:

process.env.GHOST_API_URL
process.env.GHOST_CONTENT_API_URL

is a breeze.

Deploying Ghost to production is a little trickier. You have two options:

Let Ghost take care of everything using Ghost(Pro)
Self-host your Ghost instance

Ghost(Pro) has a starter package that starts at $9 a month, and although this isn't bad for what you get, they do not support custom themes. Unfortunately JAMStack falls into this category, as you need to create a custom integration to gain access to your CONTENT_API_KEY. In order to get this you'd have to go with their creator option at $25 a month.

Your other option is to self-host. Ghost has some great documentation on how to do this using a variety of avenues. Your mileage may vary.

Regardless of which choice you go with, you're going to want to make sure that you supply your NextJS app with the production GHOST_API_URL and GHOST_CONTENT_API_KEY values. These can be found in your production instance of Ghost once you deploy.

Conclusion

I hope you found this article helpful. I've been experimenting with Ghost a lot in the last few weeks and I hope to continue to build out my site to support some of its awesome features. Next I'll be writing up a tactic for integrating your JAMStack with Ghost's Members feature, so stay tuned for that! And as always, if you have questions feel free to reach out on Twitter.

Happy coding ⚡️

Subscribing Ghost Members From Your JAMStack Site

Jake Wiesler — Thu, 26 Aug 2021 14:05:17 +0000

In a previous post we walked through a basic blog setup using NextJS and Ghost as a headless CMS. In this post, we'll take things up a notch by adding support for Ghost Memberships, a new feature in v4.0.

Ghost Memberships

Memberships is a native feature to Ghost. It is essentially an email list that readers of your site can subscribe to. They can choose to subscribe as free or paid members, and the Ghost Dashboard displays analytics like Total Members, Email Open Rate and Monthly Recurring Revenue.

Ghost's official themes support memberships out-of-the-box, meaning you get form inputs and subscribe buttons throughout. No extra work needed. And most custom themes purchasable through the Themes Directory also support memberships.

As a writer this means you can publish posts and choose to send them to any and all of your members with one click of a button. It's a powerful model for content creators who want to capture some of the value they create via monetization.

However, if you use Ghost as a headless CMS, you're opting out of this native functionality and can only take advantage of it through Ghost's APIs. Specifically the Admin API.

Ghost's Admin API

The Admin API exposes a set of endpoints that let you do things you would normally do in the Ghost Dashboard. Things like creating, editing and deleting posts and static pages, uploading images and themes, or manipulating the site object.

You can also perform basic CRUD operations on your list of members.

In this post we are only concerned with the creation of a member, i.e subscribing.

Installing the client

At the time of writing this post, interacting with member data via the Admin API is an undocumented feature. I was not able to find any reference to it within Ghost's developer documentation, and the only reason I know about this is through hours of poking around a number of Ghost's GitHub repositories, specifically this one, this one and this one. Oh and this one.

I will keep my eye out for any changes on Ghost's end and update this post when applicable.

Even though it is undocumented, Ghost still considers the members endpoints stable, so we shouldn't have much to worry about. The only obstacle is figuring out how to use it.

First, we need to install the Admin API client:

yarn add @tryghost/admin-api

or with npm:

npm install @tryghost/admin-api

Configuring the client

Configuring this client is the same as configuring the Content API client from the previous post. If you are confused how we got here, I recommend reading that one first.

Let's add on to our lib/ghost.js file by importing the Admin API client and initiating it:

import GhostAdminAPI from '@tryghost/admin-api'

const admin = new GhostAdminAPI({
  url: '',
  key: '',
  version: ''
})

As with the Content API, the Admin API requires a url and a key value. They can be found in the Integrations section of your Ghost Dashboard as well. In fact, the url value will be the same for the Content API client and the Admin API client. The only difference is the key.

To find them, navigate to your locally hosted Ghost instance, which is usually deployed at http://localhost:2368/ghost.

If you do not have Ghost running locally, see the previous
post for more details.

Once there, navigate to the Integrations section on the left sidebar. If you have yet to create a custom integration for Ghost, you will need to do so by clicking "Add Custom Integration". You can name the integration whatever you want.

If you are continuing on with the previous post, your custom integration should already exist, "NextJS Front-end".

Once you've confirmed that your custom integration exists, open it to see more information. This is where you will find your url and key values. The value of url will correspond to the API URL value, and the value of key will correspond to ADMIN API key.

Copy these values into a .env.local file:

GHOST_API_URL=<YOUR_API_URL>
GHOST_ADMIN_API_KEY=<YOUR_ADMIN_API_KEY>

If you are following along from the previous
post in this series, you may already have the GHOST_API_URL in your .env.local file.

Now that we have that sorted, lets update lib/ghost.js with these values:

import GhostAdminAPI from '@tryghost/admin-api'

const admin = new GhostAdminAPI({
  url: process.env.GHOST_API_URL,
  key: process.env.GHOST_ADMIN_API_KEY,
  version: 'v3'
})

We also updated the version by using "v3". This is the value Ghost currently uses in their documentation.

It's important to note that the url and key values will be different in your production instance of Ghost. Since we are injecting these values as environment variables, it should be trivial to update them for production. Wherever you deploy your JAMStack site, just make sure to include the production values of GHOST_API_URL and GHOST_ADMIN_API_KEY in your environment variable configuration.

Subscribing members

Now that we have the client setup, we'll need to write a function that adds a member to our list. This was the tricky part about the Admin API. There is no documentation on how to do so. After some digging around, I came up with this:

const admin = new GhostAdminAPI({ /* ... */ })

export function addMember(email, name) {
  return admin.members.add({ email, name });
}

The addMember function above accepts an email and a name. Only email is required by the API, though the name will also be set if you include it.

The form to capture these values can be built in any way you choose. I won't include that in this post. Just make sure that when the form submits, you call addMember and pass the right values.

In development, you should be able to call this function and see the newly added member show up in the Members section of your local instance of Ghost. This is how you know it is working properly.

Sending a confirmation email

One of the great things about Ghost's native Members feature is that a reader will receive a special email when they subscribe for the first time. It is a feature that I want to support on my site, but again, there's no documentation on how to do this.

After some more digging I was able to find a few options that can be passed along with the email and name that make this possible:

const admin = new GhostAdminAPI({ /* ... */ })

export function addMember(email, name) {
  return admin.members.add(
    { email, name },
    { send_email: true, email_type: 'subscribe' });
}

These options are not required, but the Members API will look for them, and if they are passed, a special email will be sent to your member. Pretty neat!

Finding a bug in Ghost's email logic

During this process of discovering how to send subscription emails to new members, I realized that the content of the email being sent had nothing to do with confirming a subscription. Instead it contained a magic link to "Sign In" to my website.

The image above is a snapshot of the output from the command ghost log, which can be run in development to inspect the logs of your running Ghost instance.

Why would this be?

If you use an official Ghost theme like Casper, your members can sign in to view paywalled content, and this email enables that. But I'm not requesting that my members sign in, I'm requesting that they confirm their subscription.

If we take a step back to the options passed to the addMember function, you'll notice there is an email_type option being used. This option can have one of three values:

'signin'
'signup'
'subscribe'

The value of this email_type is used to select one of three different email templates to be sent to the member. Since we are using 'subscribe', you would think that the subscribe template would be sent, but that's not the case.

I did some debugging through the various repositories in Ghost's GitHub organization, and have found what I believe to be a bug in the way that email templates are selected when adding a member from the @tryghost/admin-api client.

If you're curious to know more, I've laid out my thesis in a new issue in the TryGhost/Ghost repository on GitHub. I'll make sure to keep this post updated if the issue gets resolved.

Conclusion

So there you have it. It's not a perfect solution by any means, but if you are using Ghost as a headless CMS, this is currently the way to add members to your Ghost dashboard.

Hopefully, with continued growth in the JAMStack ecosystem, some of these issues will get ironed out over time. That's the beauty of open source!

Feel free to reach out to me on Twitter if you have any further questions regarding this post.

Happy coding ⚡️

I'm Leaving VSCode for Vim

Jake Wiesler — Wed, 10 Mar 2021 00:00:00 +0000

I started programming in 2014. At that time, VSCode didn’t exist. At that time, I didn’t know about Vim either. I knew of two text editors: Atom and Sublime Text. I tried Sublime first. Remember that popup you would get when you didn’t pay for the license? 😅 Good times.

I switched to Atom shortly thereafter. Atom was marketed as a hackable text editor. This appealed to me. It was my first exposure to configuring a development environment. The colors, the keybindings, the plugins, etc.

In late 2015 I started seeing a ton of buzz around a new text editor named VSCode. I knew of Visual Studio, the IDE. But this was an entirely new product from Microsoft. After a while it was hard to ignore. I adopted VSCode in mid-2016, and it's been my text editor ever since. But after 5 years I've decided to make the switch to Vim full time.

The case for VSCode

Before I go down the rabbit hole that is Vim, let me first address VSCode. It’s an incredible piece of software. And to be honest, there’s no rational reason for me to stop using it. It does everything I need it to do.

I have it configured exactly how I want, and it’s not a headache to do so. The plugin ecosystem is massive. There are hundreds, maybe thousands, of themes. It has an integrated terminal. For TypeScript, it’s an absolute dream. You can alter VSCode to be anything you want it to be, but most important:

It just gets the job done.

All of these aspects of the product make it a joy to use, and it’s probably why VSCode has taken off and left everything else in the dust. Here’s a graphic from the State of JS Survey in 2020.

VSCode is good. There’s a reason it’s so popular. And let me tell you, it’s a hard drug to quit. So why the hell would I leave?

Vim's alluring nature

I used Vim early in my development career for a single purpose: Git commits. Vim opens up, I write my message, and I’m out. It was the epitome of scratching the surface.

This went on for years. It wasn’t until I saw The Primeagen on Twitch about a year ago that I gave the text editor a thought. If you’ve never seen this dude in action, you have to. Even if you have no desire to use Vim (in which case I’m not sure why you’ve made it this far), you must. He showed me that there are levels to text editing, and I was clearly on level 0.

Copying and pasting with my mouse. Moving through files with my mouse. Searching for files in the file tree. Looking up that keymap I still hadn’t memorized. This is how I did things, because it’s how I always did them. I was so busy trying to learn how to code that I never had time to consider improving my process. I never considered efficiency.

And don’t get me wrong, I don’t think there’s anything wrong with this. Thousands of people work this way every day and they get the job done. But I’m the type of person that’s always looking for an edge, and I think Vim can be an edge.

There’s a common phrase, even a book title, that’s used to describe Vim:

Precision editing at the speed of thought.

The Primeagen is the ultimate example of this. He has a level of command over his text editor that I’ve never seen, and that is a concept that really strikes home with me. If you use a tool every day, it makes sense to know it inside and out.

I think it’s possible to achieve this level of efficiency with VSCode as well. As I said earlier, there’s no rational reason to make the switch. But Vim has lured me into its cave of wonder, and I might be too far in to turn back.

The transition process

The first thing I did was add the Vim plugin to VSCode, giving me an opportunity to learn the basic movements in a familiar place. The plan was to get these basics down and then start migrating over to Vim, but life got in the way.

Weeks turned into months, and I kept pushing off the day where I’d take the leap. There are certain parts of my day job that require a high level of output, and switching up my development workflow was a chore I just didn’t want to put up with.

Even so, I was developing a level of proficiency with Vim movements that made it easier to consider the switch. I wasn’t thinking about what keys to press anymore. Instead I just pressed them. My muscle memory was improving. I started layering on advanced movements, and I was developing a preference for certain actions.

Let me tell you, editing text in this way is a whole lot of fun. You really feel like a wizard once you get the hang of it. I was spending less time reaching for the mouse. Any time I did, I would ask myself if what I’m trying to do can be solved with a keystroke. Almost always the answer is yes.

How it's going

A few weeks ago I decided to bite the bullet and go all in. I feel really comfortable with the tool itself, I just need a proper development environment. The goal now is to make Vim feel cozy.

VSCode abstracts away much of the heavy lifting that comes with a good development environment. Things like language support, formatting, search, diagnostics, etc. Vim doesn’t support these out-of-the-box, and they are paramount to my workflow. Configuring them is the biggest obstacle to entry, and I definitely underestimated how much work it would take.

So far, I've managed to get a pretty decent setup. I'm using Neovim instead of vanilla Vim, which has a vibrant community and an active development team. I have a good base of plugins, and my dotfiles are starting to look like proper dotfiles.

The title of this post specifically mentions Vim, but what I've really fallen in love with is Neovim. I believe I've stumbled upon a really great tool that is actively being developed, and that is a dream for someone like me who plans to use it long term.

There is still a lot to learn, and over the next few weeks I'll be sharing how I'm going about the process. If you'd like to learn more about my transition to Vim, and get access to the content I'll be putting out, you can subscribe to my newsletter or follow me on dev.to.

Any questions? Just want to say hi? Reach out to me on Twitter.

Happy building!

What are your favorite JAMStack CMSs?

Jake Wiesler — Mon, 10 Aug 2020 20:02:24 +0000

I'm working on a small project for a client that requires a basic blog setup. Nothing too fancy. I'm planning to build the site with NextJS, and am looking for a way to make content creation easy for the client.

So far I've explored Sanity.io and Contentful. Initial impressions have been interesting. Curious to hear everyone's thoughts.

How often are you increasing font size on blog posts?

Jake Wiesler — Sat, 08 Aug 2020 23:02:43 +0000

I have been doing this a lot lately. I'm not sure if it's just my age showing, or my shitty eye sight (boy I hope not), or the fact that my monitors are higher rez, but I really enjoy reading with large type that fills the entire screen.

Hell, I even do this with my own site and it makes me want to go and refactor my font size setup.

Anyone else find themselves doing the same?

Deep Work and Music - What are some of your favorite artists / songs / playlists when working?

Jake Wiesler — Sat, 08 Aug 2020 22:46:39 +0000

Would love to get more variety in what I'm listening to. I struggle with any audio that has lyrics, so most of what I listen to falls into the categories:

lofi
classical
instrumental

But I do enjoy some upbeat techno when I'm in a groove. Usually when I'm trying to figure out a difficult problem I opt for silence first.

Curious to hear how everyone else approaches audio when working?

DEV Community: Jake Wiesler

Essential Vim Movements

Table Of Contents

Up, down, left and right

Up, down, left and right, but faster

Tip: Use the scrolloff setting

Jump to the beginning of a line

Jump to the end of a line

Jump to a specific line

Tip: Use relative numbers

Search for text

Tip: Improve search experience

Conclusion

Setup Zsh As Your Default Shell

Prerequisite: Install Zsh

Step 1

Locate Zsh's executable filepath

Append Zsh's executable filepath to /etc/shells

Step 2

Conclusion

Getting Started With Vim - A Practical Guide

Table of contents

Neovim

Installation

init.vim

General settings

Plugins

vim-plug

A color scheme

Telescope

Lightline

vim-fugitive

gitsigns

Language support

Lspconfig

Install a language server

Configure the language server

Autocompletion

Treesitter

Remaps

Tips and tricks

Conclusion

Manage Your Dotfiles Like a Superhero

What you're probably doing

What you should be doing

How to do it

Understanding stow

One more example

Storing dotfiles in git

Conclusion

The Next Iteration of the Web

Web 2.0

Data wars

Enter Web 3.0

The early adopters

Build a JAMStack Blog with NextJS and Ghost

The beauty of Ghost

My issues with Ghost

Enter the JAMStack

Installing Ghost

Installing NextJS

Querying for blog posts

url and key

version

Render a list of blog posts

Creating pages for each post

Rendering post content

Rendering post tags

Deploying to production

Conclusion

Subscribing Ghost Members From Your JAMStack Site

Ghost Memberships

Ghost's Admin API

Installing the client

Configuring the client

Subscribing members

Sending a confirmation email

Finding a bug in Ghost's email logic

Conclusion

I'm Leaving VSCode for Vim

Tip: Use the `scrolloff` setting

Append Zsh's executable filepath to `/etc/shells`

Understanding `stow`

`url` and `key`

`version`