Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Easy note taking in Vim
VimL Python HTML

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
autoload/xolox
doc
ftplugin
misc/notes
plugin
syntax
INSTALL.md
README.md
TODO.md

README.md

Easy note taking in Vim

The notes.vim plug-in for the Vim text editor makes it easy to manage your notes in Vim:

  • Starting a new note: Execute the :Note command to create a new buffer and load the appropriate file type and syntax
    • You can also start a note with Vim commands like :edit, :tabedit and :split by starting the filename with note:, as in :edit note:todo (the part after note: doesn't have to be the complete note title and if it's empty a new note will be created)
    • You can start a new note with the selected text as title using the :NoteFromSelectedText command
  • Saving notes: Just use Vim's :write and :update commands, you don't need to provide a filename because it will be set based on the title (first line) of your note (you also don't need to worry about special characters, they'll be escaped)
  • Editing existing notes: Execute :Note anything to edit a note containing anything in its title (if no notes are found a new one is created with its title set to anything)
    • The :Note and :DeleteNote commands support tab completion of note titles
  • Deleting notes: The :DeleteNote command enables you to delete the current note
  • Searching notes: :SearchNotes keyword … searches for keywords and :SearchNotes /pattern/ searches for regular expressions
    • Smart defaults: Without an argument :SearchNotes searches for the word under the cursor (if the word starts with @ that character will be included in the search, this means you can easily search for @tagged notes)
    • Back-references: The :RelatedNotes command find all notes referencing the current file
    • A Python 2 script is included that accelerates keyword searches using a keyword index
    • The :RecentNotes command lists your notes by modification date, starting with the most recently edited note
  • Navigating between notes: The included file type plug-in redefines gf to jump between notes and the syntax script highlights note names as hyper links
  • Writing aids: The included file type plug-in contains mappings for automatic curly quotes, arrows and list bullets and supports completion of note titles using Control-X Control-U and completion of tags using Control-X Control-O
  • Embedded file types: The included syntax script supports embedded highlighting using blocks marked with {{{type … }}} which allows you to embed highlighted code and configuration snippets in your notes

Here's a screen shot of the syntax mode using the slate color scheme:

Syntax mode screen shot

Install & usage

Unzip the most recent ZIP archive file inside your Vim profile directory (usually this is ~/.vim on UNIX and %USERPROFILE%\vimfiles on Windows), restart Vim and execute the command :helptags ~/.vim/doc (use :helptags ~\vimfiles\doc instead on Windows). To get started execute :Note or :edit note:, this will start a new note that contains instructions on how to continue from there (and how to use the plug-in in general).

Options

All options have reasonable defaults so if the plug-in works after installation you don't need to change any options. They're available for people who like to customize their directory layout. These options can be configured in your vimrc script by including a line like this:

let g:notes_directory = '~/Documents/Notes'

Note that after changing an option in your vimrc script you have to restart Vim for the changes to take effect.

The g:notes_directory option

All your notes are stored together in one directory. This option defines the path of this directory.

The g:notes_suffix option

The suffix to add to generated filenames. The plug-in generates filenames for your notes based on the title (first line) of each note and by default these filenames don't include an extension like .txt. You can use this option to make the plug-in automatically append an extension without having to embed the extension in the note's title, e.g.:

:let g:notes_suffix = '.txt'

The g:notes_title_sync option

When you rename a file in your notes directory but don't change the title, the plug-in will notice this the next time you open the note in Vim. Likewise when you change the title in another text editor but don't rename the file. By default the plug-in will prompt you whether you want it to update the title of the note, rename the file on disk or dismiss the prompt without doing anything.

If you set this option to the string 'no' this feature will be completely disabled. If you set it to 'change_title' it will automatically change the title to match the filename. If you set it to 'rename_file' it will automatically rename the file on disk to match the title.

The g:notes_smart_quotes option

By default the notes plug-in automatically performs several substitutions on the text you type in insert mode. Here are those substitutions:

  • ' becomes or depending on where you type it
  • " becomes or (same goes for these)
  • -- becomes
  • -> becomes
  • <- becomes
  • the bullets *, + and - become

If you don't want the plug-in to perform these substitutions, you can set this option to zero like this:

:let g:notes_smart_quotes = 0

The g:notes_shadowdir option

The notes plug-in comes with some default notes containing documentation about the plug-in. This option defines the path of the directory containing these notes.

The g:notes_indexfile option

This option defines the pathname of the optional keyword index used by the :SearchNotes to perform accelerated keyword searching.

The g:notes_indexscript option

This option defines the pathname of the Python script that's used to perform accelerated keyword searching with :SearchNotes.

The g:notes_tagsindex option

This option defines the pathname of the text file that stores the list of known tags used for tag name completion and the :ShowTaggedNotes command. The text file is created automatically when it's first needed, after that you can recreate it manually by executing :IndexTaggedNotes (see below).

Commands

To edit one of your existing notes you can use Vim commands such as :edit, :split and :tabedit with a filename that starts with note: followed by (part of) the title of one of your notes, e.g.:

:edit note:todo

This shortcut also works from the command line:

$ gvim note:todo

When you don't follow note: with anything a new note is created.

The :Note command

When executed without any arguments this command starts a new note in the current window. If you pass one or more arguments the command will edit an existing note containing the given words in the title. If more than one note is found you'll be asked which note you want to edit. If no notes are found a new note is started with the given word(s) as title.

This command will fail when changes have been made to the current buffer, unless you use :Note! which discards any changes.

This command supports tab completion: If you complete one word, all existing notes containing the given word somewhere in their title are suggested. If you type more than one word separated by spaces, the plug-in will complete only the missing words so that the resulting command line contains the complete note title and nothing more.

The :NoteFromSelectedText command

When you execute this command it will start a new note with the selected text as the title of the note.

The :DeleteNote command

The :DeleteNote command deletes a note file, destroys the buffer and removes the note from the internal cache of filenames and note titles. If you pass a note name as an argument to :DeleteNote it will delete the given note, otherwise it will delete the current note. This fails when changes have been made to the buffer, unless you use :DeleteNote! which discards any changes.

The :SearchNotes command

This command wraps :vimgrep and enables you to search through your notes using one or more keywords or a regular expression pattern. To search for a pattern you pass a single argument that starts/ends with a slash:

:SearchNotes /TODO\|FIXME\|XXX/

To search for one or more keywords you can just omit the slashes, this matches notes containing all of the given keywords:

:SearchNotes syntax highlighting

:SearchNotes understands @tags

If you don't pass any arguments to the :SearchNotes command it will search for the word under the cursor. If the word under the cursor starts with '@' this character will be included in the search, which makes it possible to easily add @tags to your @notes and then search for those tags. To make searching for tags even easier you can create key mappings for the :SearchNotes command:

" Make the C-] combination search for @tags:
imap <C-]> <C-o>:SearchNotes<CR>
nmap <C-]> :SearchNotes<CR>

" Make double mouse click search for @tags. This is actually quite a lot of
" fun if you don't use the mouse for text selections anyway; you can click
" between notes as if you're in a web browser:
imap <2-LeftMouse> <C-o>:SearchNotes<CR>
nmap <2-LeftMouse> :SearchNotes<CR>

These mappings are currently not enabled by default because they conflict with already useful key mappings, but if you have any suggestions for alternatives feel free to contact me through GitHub or at peter@peterodding.com.

Accelerated searching with Python

After collecting a fair amount of notes (say more than 5 MB) you will probably start to get annoyed at how long it takes Vim to search through all of your notes. To make searching more scalable the notes plug-in includes a Python script which uses a persistent full text index of your notes stored in a file.

The first time the Python script is run it will need to build the complete index which can take a moment, but after the index has been initialized updates and searches should be more or less instantaneous.

The :RelatedNotes command

This command makes it easy to find all notes related to the current file: If you are currently editing a note then a search for the note's title is done, otherwise this searches for the absolute path of the current file.

The :RecentNotes command

If you execute the :RecentNotes command it will open a Vim buffer that lists all your notes grouped by the day they were edited, starting with your most recently edited note. If you pass an argument to :RecentNotes it will filter the list of notes by matching the title of each note against the argument which is interpreted as a Vim pattern.

The :ShowTaggedNotes command

To show a list of all notes that contains @tags you can use the :ShowTaggedNotes command. If you pass a count to this command it will limit the list of tags to those that have been used at least this many times. For example the following two commands show tags that have been used at least ten times:

:10ShowTaggedNotes
:ShowTaggedNotes 10

The :IndexTaggedNotes command

The notes plug-in defines an omni completion function that can be used to complete the names of tags. To trigger the omni completion you type Control-X Control-O. When you type @ in insert mode the plug-in will automatically start omni completion.

The completion menu is populated from a text file listing all your tags, one on each line. The first time omni completion triggers, an index of tag names is generated and saved to the location set by g:notes_tagsindex. After this file is created, it will be updated automatically as you edit notes and add/remove tags.

If for any reason you want to recreate the list of tags you can execute the :IndexTaggedNotes command.

Other plug-ins that work well with the notes plug-in

  • The utl.vim universal text linking plug-in enables links between your notes, other local files and remote resources like web pages
  • My shell.vim plug-in also enables easy navigation between your notes and environment like local files and directories, web pages and e-mail addresses
  • The VOoM outlining plug-in should work well for notes if you use the Markdown style headers starting with #, however it has been reported that this combination may not always work so well in practice (sometimes losing notes!)

Contact

If you have questions, bug reports, suggestions, etc. the author can be contacted at peter@peterodding.com. The latest version is available at http://peterodding.com/code/vim/notes/ and http://github.com/xolox/vim-notes. If you like the script please vote for it on Vim Online.

License

This software is licensed under the MIT license.
© 2011 Peter Odding <peter@peterodding.com>.

Something went wrong with that request. Please try again.