cheatsheet.nvim

A searchable cheatsheet for neovim from within the editor using Telescope (fallback to displaying in a floating window if Telescope is not installed) with command autofill, bundled cheats for the editor, vim plugins, nerd-fonts, etc because hoomans suck at remembering stuff:

^{Font: mononoki, Colorscheme: onedark, Dotfiles}

Table of Contents

• Features
• Quickstart
• Installation
• Usage
  • Auto Fill Commands From Telescope
• Bundled Cheatsheets
• Configuration
• cheatsheet.txt File Format
• For Plugin Authors
• Acknowledgements

Features

• Telescope interface to quickly find what you're looking for
• Simple and portable cheatsheet format -- simple text file, no lua or vimscript involved
• Fill out command line automatically (without execution) if selected item in Telescope is a :command
• Bundled cheatsheets for:
  • nerd-fonts, box drawing characters, lua patterns, etc
  • other plugins like gitsigns, sandwich, easy-align, etc
• Enable bundled plugin cheatsheets only for plugins you have installed locally
• Use a cheatsheet.txt file from other installed plugins if found in their directories
• Copy cheats directly from Telescope interface

Quickstart

1. Forget how to do X
2. Hit <leader>? to invoke cheatsheet telescope
3. Type in X and find forgotten mapping/command
4. No more ???
5. Profit !!

Installation

Installing Telescope is not required, but highly recommended for using this plugin effectively. popup.nvim and plenary.nvim are used by Telescope.

Using vim-plug

Plug 'sudormrfbin/cheatsheet.nvim'

Plug 'nvim-lua/popup.nvim'
Plug 'nvim-lua/plenary.nvim'
Plug 'nvim-telescope/telescope.nvim'

Using dein

call dein#add('sudormrfbin/cheatsheet.nvim')

call dein#add('nvim-lua/popup.nvim')
call dein#add('nvim-lua/plenary.nvim')
call dein#add('nvim-telescope/telescope.nvim')

Using packer.nvim

use {
  'sudormrfbin/cheatsheet.nvim',

  requires = {
    {'nvim-telescope/telescope.nvim'},
    {'nvim-lua/popup.nvim'},
    {'nvim-lua/plenary.nvim'},
  }
}

Subscribe to the Updates issue thread to be notified about new features.

Usage

Use the :Cheatsheet command which automatically uses Telescope if installed or falls back to showing all the cheatsheet files concatenated in a floating window. A default mapping <leader>? is provided for :Cheatsheet (not bound if already in use). By default the <leader> key is \.

Your cheatsheet file is a simple text file with the name cheatsheet.txt found in ~/.config/nvim/ (~/AppData/Local/nvim/ if you're on Windows) alongside your init.vim. Use the :CheatsheetEdit command to open it in a buffer to edit.

Telescope mappings	Description
<C-E>	Edit user cheatsheet à la :CheatsheetEdit
<C-Y>	Yank the cheatcode
Enter	Fill in the command line; see below

Auto Fill Commands From Telescope

On Enter, if the current selection is a command, it will be filled in the command line as if you had typed it (it won't be executed yet). Note that it will stop filling the command line when it encounters a { or [. So if the cheat is :set textwidth={n}, your commandline will have :set textwidth= typed into it and the cursor at end.

Since cheatsheet.nvim provides it's own commands, it is not required to "load" cheatsheet.nvim with Telescope which is usually required for plugins using Telescope.

Bundled Cheatsheets

These are the cheatsheets shipped with cheatsheet.nvim (PRs welcome!):

• default (vim builtin commands and mappings)
• nerd-fonts (useful for ricing paired with <C-Y> for copying the symbol)
• unicode (currently only has box drawing characters)
• regex (PCRE)
• markdown (not fully featured yet)

Plugin cheatsheets (click to expand)

Ideally plugin authors would supply their own cheatsheet.txt, but since that is not possible for every plugin, they are collected in cheatsheets/plugins.

• auto-session
• gitsigns.nvim
• telescope.nvim
• vim-easy-align
• vim-sandwich
• goto-preview
• octo.nvim

Configuration

This is the default configuration:

require("cheatsheet").setup({
    -- Whether to show bundled cheatsheets

    -- For generic cheatsheets like default, unicode, nerd-fonts, etc
    -- bundled_cheatsheets = {
    --     enabled = {},
    --     disabled = {},
    -- },
    bundled_cheatsheets = true,

    -- For plugin specific cheatsheets
    -- bundled_plugin_cheatsheets = {
    --     enabled = {},
    --     disabled = {},
    -- }
    bundled_plugin_cheatsheets = true,

    -- For bundled plugin cheatsheets, do not show a sheet if you
    -- don't have the plugin installed (searches runtimepath for
    -- same directory name)
    include_only_installed_plugins = true,

    -- Key mappings bound inside the telescope window
    telescope_mappings = {
        ['<CR>'] = require('cheatsheet.telescope.actions').select_or_fill_commandline,
        ['<A-CR>'] = require('cheatsheet.telescope.actions').select_or_execute,
        ['<C-Y>'] = require('cheatsheet.telescope.actions').copy_cheat_value,
        ['<C-E>'] = require('cheatsheet.telescope.actions').edit_user_cheatsheet,
    }
})

For example if you want to bind Enter to directly execute commands without autofilling them and instead want Alt-Enter to autofill, put this in your config:

require('cheatsheet').setup({
    telescope_mappings = {
        ['<CR>'] = require('cheatsheet.telescope.actions').select_or_execute,
        ['<A-CR>'] = require('cheatsheet.telescope.actions').select_or_fill_commandline,
    }
})

bundled_cheatsheets and bundled_plugin_cheatsheets can also be tables to have more fine grained control for selective usage:

require("cheatsheet").setup({
    bundled_cheatsheets = {
        -- only show the default cheatsheet
        enabled = { "default" },
    },
    bundled_plugin_cheatsheets = {
        -- show cheatsheets for all plugins except gitsigns
        disabled = { "gitsigns.nvim" },
    }
})

cheatsheet.txt File Format

• # starts a normal comment, blank lines are ignored.

• ## starts a metadata comment for specifying sections and tags.

  ## section-name @tag1 @tag2: here section-name is the name of a plugin or a simple name to group some cheats together. tag1 and tag2 are alternative names that you might later remember the section name with. For example the section name can be sandwich and the tag can be @surround.

• A cheat consists of a description and the key/command/anything separated by |

  Open cheatsheet | <leader>?
  Open cheatsheet in floating window | :CheatSheet!
  
  View mappings | :map [mapping]
  Set text width to {n} | :set tw={n}
  

  Like help files, anything in square brackets is [optional] and anything in curly brackets is {required} arguments. Some commands require a register or mark or number before them, and they are marked with {r}, {m}, {n}, etc. These are not hard and fast rules, simply conventions in the default cheatsheet -- you can of course ignore them when writing your own cheats (though if you want commands to be presented in the command line properly on pressing Enter, see the note about it in the Usage section.)

See this project's cheatsheet and the default included one for more examples.

For Plugin Authors

You can put a cheatsheet.txt file in the root of your repo (like in this repo) and it will be picked up automatically and displayed on :Cheatsheet. You don't have to add the file to your repo solely to support searching it using cheatsheet.nvim -- the format is simple enough to be opened and read normally and can serve as a great quickstart for users.

Acknowledgements

This plugin was inspired by (and borrowed some code and the default cheatsheat) from cheat40.