So it should come as no surprise that I use a variety of tools to help me when writing markdown in (n)vim.

What are the tools?

The aareman/vim-markdown plugin provides the core functionality, and features syntax highlighting. What's great is that in a terminal that supports it, you'll actually see things appear in bold, italics, or underlined. Headers, links, and monospace text each get a different color, and sometimes even weight.

From there, I have a number of other plugins that augment the functionality from vim-markdown:

• vim-table-mode provides on-the-fly autoformatting of textual tables, including those in Markdown. This is invaluable, as it allows me to see as I type if I'm missing columns, adding extra columns, etc.
• img-paste.vim allows pasting a screenshot into a markdown document. It will copy the screenshot to a specified relative directory, and then create the markup for displaying it in the document.
• vim-pandoc-syntax does much of the heavy lifting for syntax highlighting, particularly when it comes to fenced code blocks. If you use Github Flavored Markdown, you can optionally specify a language when creating a fenced code block; vim-pandoc-syntax will identify the language, and use it to provide syntax highlighting within the code block for the given language.

Additionally, with coc.nvim, I get integration with markdownlint, which flags potential syntax and style issues.

How I configure it

I configure vim-markdown using the following:

let g:markdown_disable_folding            = 1
let g:markdown_disable_motions            = 0
let g:markdown_disable_spell_checking     = 0
let g:markdown_disable_conceal            = 0
let g:markdown_disable_table_mode         = 0
let g:markdown_disable_pandoc_integration = 0
let g:markdown_disable_clean_empty_on_cr  = 0

nnoremap <buffer> <Leader>x :call markdown#SwitchStatus()<CR>

These do the following:

• I rarely use code folding, and when I do, I want to do it manually. As such, I disable auto-folding done by the plugin.
• vim-markdown provides a variety of motions that let you jump around more quickly in a markdown document, particularly to the previous header ([[) or the next header (]]). I want to keep these around.
• Spell checking is nice.
• "conceal" will conceal markup sigils when you're not on a line; the terminal continues to highlight them appropriately (e.g. bold, italic, underlined, etc.). Links are collapsed to just the highlighted linked text, collapsing the content around them. Doing this makes reading the document easier; when you're on the line, it will reveal all concealed characters so you can edit.
• Table mode enables the integration with vim-table-mode; I definitely want this.
• Pandoc integration enables the pandoc syntax highlighting; I definitely want this.
• If I hit Enter from a list item, it creates a new list item. This last setting means that I can hit Enter again, and it will clear the list item and start a line below. It's an easy way to end a list and start typing the next paragraph.
• I often use GFM checkboxes for TODO lists. The mapping declaration maps <Leader>x to toggle the checkbox.

Final thoughts

After vim-surround and coc.nvim, this is undoubtedly the plugin that gives me the most value. I benefited from it typing up this very blog post! While a GUI IDE can provide side-by-side editing where you can see how the Markdown is transformed, I rarely need that; the whole point of Markdown is to provide a human readable format that provides contextual markup. Reading the raw file should be enough.

vim-markdown gives me the ability to have a raw Markdown file, while simultaneously giving me just enough visual context to understand things even when skimming a document.

Advent 2023: (n)vim Plugins: vim-markdown was originally published 19 December 2023 on https://mwop.net by Matthew Weier O'Phinney.

That's where vim-fugitive comes into play.

What does it solve?

Fugitive integrates with git, plain and simple. It exposes a number of commands and functions that allow you to do common operations quickly, but also has some deeper bindings to allow doing more complex things such as viewing a file from previous commits, or performing a diff between the staged and working version, or using git blame within vim.

How do I use it?

Admittedly, I use a very small subset of what Fugitive provides.

On a daily basis, I use :Gwrite to stage changes, and :G to view the status of the working tree. When in the status view, I often use cc to commit changes, which splits open a pane for writing the commit message. I also use :GRemove when I want to remove a file from the tree.

Something else that has come in handy when reviewing code with others: :GBrowse can open the file in the canonical repository, using the visual selection as the line range, allowing you to quickly share a link to specific code to review.

Final Thoughts

This plugin does exactly what it says on the tin. I love the fact that it integrates with the underlying git command, as that follows the Unix Philosophy of doing one thing well, and piping out to other processes to perform complex behavior. For me, the fact that I can stay directly within my editor and still get full access to git when needed is tremondously powerful.

Advent 2023: (n)vim Plugins: vim-fugitive was originally published 18 December 2023 on https://mwop.net by Matthew Weier O'Phinney.

What is coc.nvim?

The plugin name is an acronym for "Conquer of Completion", and its goal is to "Make your Vim/Neovim as smart as VS Code". While it can be used with either vim or neovim, it has some optimizations under the hood to allow usage with neovim's language server protocol support, which allows it to expose more features and perform better when using that editor.

The language server protocol exposes features like (per the neovim documentation) "go-to-definition, find-references, hover, completion, rename, format, refactor, etc., using semantic whole-project analysis."

In practice, this means the following:

• You get signature hints. In PHP, this will pick up hints from the signature, but also hints from docblocks.
• You get completion. Hitting <Tab>, you'll see a list of possible matches.
  • When in PHP, if the match is for a class name, it will add the import statements for you.
  • Also in PHP, if the match is for a method that exists in an implemented interface or a parent class, it will complete the signature for you, and perform any imports required.
• If your cursor is on something like a property name, a method name, a class name, or more, you can jump to the definition (I have this mapped to gd, for "go to definition).
• Depending on the language server in use, you may also get the ability to do limited refactoring, such as changing a variable/property name throughout a file, or renaming a method and all calls to it.

Interestingly enough, the LSP is what is used under-the-hood by IDEs like VS Code, so I'm getting the same features I'd get using a dedicated IDE!

These features helped me so much, I ponied up for an Intelephense license.

If neovim already supports language servers natively, why use coc.nvim?

I use a variety of languages, and the configuration for each varies widely. On top of that, when I started using neovim, I wasn't yet familiar with Lua, which is how you configure things like the LSP. But even once I learned... the documentation for the various LSP implementations is often missing or inscrutable; it's hard to know what options are available, and how to modify the behavior programmatically.

coc.nvim just takes care of it, gives me a single location for configuration, gives me a single set of keybindings to remember, and provides a unified interface for operations like jumping to definitions, performing refactors, and more.

Less futzing, more working.

Why was this helpful?

Prior to adopting coc.nvim, I used things like ctags to provide some limited completion and ability to jump to definitions. However, this was problematic in that I would forget to regenerate ctags for a project when I added or changed dependencies, as well as when adding my own code; they were always out-of-date. Using them, I ended up having to keep a mental map in my head of the project, so that I could open the class file with a definition when needing to understand what the signature allowed, or what the method returned. This approach was fine when I was doing development every day, or working on familiar code bases, but often neither of these are true anymore.

Why not just use a "real" IDE?

Listen, IDEs are great. But even when I've taken time to get to know an IDE, I've found I'm just not as productive when using one. Vim and its descendants are highly optimized for touch typists, and make movement and selection ridiculously fast compared to using a mouse, trackpad, or visual pointer.

Having tools like coc.nvim allow me to get some of the chief benefits of an IDE from within my preferred editor. Sure, I don't get advanced refactoring tools, but I can always reach for Rector when I need to. Debugging? vim-debug gives me most of what I would need, and I can reach for a visual IDE if I need more granular control.

The LSP and coc.nvim give me the best of both worlds: excellent tooling for a touch typist, with IDE features that give contextual information when I need it.

Advent 2023: (n)vim Plugins: coc.nvim was originally published 17 December 2023 on https://mwop.net by Matthew Weier O'Phinney.

What problem does it solve?

Let's say you have a PHP associative array declaration:

[
    "name" => "Matthew",
    "status" => "online",
    "url" => "https://mwop.net"
]

Now, for some folks, this declaration is fine. However, I tend to prefer aligning the declarations, as it helps me visually parse the block more easily.

Now, I could go to each line, and insert space before the => assignment operators. This works, and for a short declaration like in this example, it's relatively quick. But when the declaration is larger, or the sizes of the keys vary a lot, this can become tedious quickly.

Another place I've used it is Markdown tables:

| Name | Status | URL |
| ---- | ------ | --- |
| Matthew | online | mwop.net |
| An Example | offline | example.com |
| API | online | api.example.com |

This demonstrates the problem even better, as you can see that the columns do not align, which makes understanding if each row has all the required columns harder.

Tabular

The tabular plugin allows you to easily tabularize text. You visually select the rows you want to line up, and then invoke it, providing a search string (a regular expression) for matching the character(s) to align against. It then does the work of determining how much space to add to each column to get things to line up.

Going back to the original example, I'd select all the entries within the array, and then:

• : to enter command mode
• Tabularize /=> to invoke tabular, and tell it to align against =>
• Enter

and then you get:

[
    "name"   => "Matthew",
    "status" => "online",
    "url"    => "https://mwop.net"
]

In the second example, I'd select all rows, including the header, and use | as the search. This results in:

| Name       | Status  | URL             |
| ----       | ------  | ---             |
| Matthew    | online  | mwop.net        |
| An Example | offline | example.com     |
| API        | online  | api.example.com |

Hint: use your tab key

The Tab key is your friend, both in vim's command mode, as well as in your shell. I generally type :Tabu[Tab], and it expands to :Tabularize for me. And, of course, you could bind it to a keystroke or function if you wanted.

However...

Interestingly, I use tabular less and less.

Why?

My coding standard tools can do code alignment, and since I have to run this anyways, I can save myself some time by just not doing alignment during my coding session.

With markdown tables, my current markdown plugins and language server configuration autoindents for me. As I finish a row, it automatically reformats the table to tabularize everything, which means I don't need to take any extra steps to format.

Final Thoughts

I keep this plugin around because when I do need it, it's super convenient, less error-prone than doing it manually, and saves me time.

Advent 2023: (n)vim Plugins: tabular was originally published 16 December 2023 on https://mwop.net by Matthew Weier O'Phinney.

I used to "collect" plugins, but at this point, particularly since switching over to neovim, I've reduced my plugins quite a bit, to only those I use on a regular basis.

So, I figured today, I'd start a mini-series as part of my Advent 2023 blogging, on some of my most used plugins.

Today's plugin: vim-surround.

What does it do?

vim-surround, at it's heart, allows you to surround a selection with a character or pair of characters.

Why is this useful?

Let's say you're writing an exception message, and suddenly realize that you forgot to put it in quotes as you close the parens:

throw new RuntimeException(This is the exception message I will present)

Normally, I might use f( to jump to the first paren, hit a to append at that point, and then hit ' to add the initial quote, and Esc to return to normal mode. I'd repeat, but use t) to jump to the character before the closing paren.

With vim-surround, I can leverage vim's selection strokes to quickly do this.

• Hit vi( from anywhere within the parentheses, which selects everything between then. I can even do this when on the ")" character; it performs the same selection.
• Hit Shift-s to trigger vim-surround
• Type ' to surround the selected text with the quotes.

This may not seem like much, but the amount of effort it saves is tremendous:

• I use it a ton when writing Markdown, to mark words or phrases as italic (_), bold ** (this one requires doing the selection twice), or just to add quotes.
• In HTML, I can use it to add tags! When you trigger vim-surround, you can start typing a tag — e.g. <em> — and vim-surround will wait until the tag is complete, and then surround the selection with that tag.
• In code, I'll often use it to surround a selection with parens or square brackets, or add quotes (as demonstrated above).

Sidebar: efficient selection

Vim provides actions that give you the ability to select (v), replace (c), delete (d), and yank (y) text. These actions operate on the selection you provide.

The selection w indicates to operate on the current word, and by default, it operates from the current position to the next word boundary. This is important: the selection is really a boundary you wish to select to.

There are modifiers you can provide for the selection: "i" means "inner", and will select everything up to the boundary, but not the boundary itself, but, more importantly, the boundary to either side of the current position.t

There are some boundaries that are particularly interesting: "(" and ")", "{" and "}", "[" and "]", "<"/">", and both quote styles, when paired with "i" or "a" modifiers, will select bewteen pairs.

In the example above, I used vi( to select everything inside the parens. "a" means "all", and acts like "i", but selects everything up to and including the boundary. If I'd used vaw in the example, it would have selected everything inside the parens, as well as the parens.

You can be really efficient in your text selection and manipulation knowing these rules, and it's when using these rules that vim-surround shines.

Final Thoughts

It's the simplicity of operations such as text selection and using vim-surround that are a key reason for sticking with vim all these years. They allow me to efficiently edit text without needing to leave the home row of the keyboard, or requriing a mouse.

So far in my career, I've avoided RSI, and I credit tools like this as a big part of that.

Advent 2023: (n)vim Plugins: vim-surround was originally published 15 December 2023 on https://mwop.net by Matthew Weier O'Phinney.

I thought I'd try an experiment: I've had a ton of ideas for blog posts, many of them short, and just... never write them. What if I were to do a personal advent, and write these up?

Let's see how far I get.

Today's topic: Logseq.

What was I trying to solve?

For many years (over a decade), I kept a little knowledge base of markdown files. I had a diary command that would open a file named after the current day's date, creating it if it didn't exist, in vim. I'd create todo lists, notes from meetings, ideas I wanted to investigate, even blog and email drafts.

When I needed to find something, I'd use a tool such as ack to search through all files.

It worked, but I noticed a lot of things:

• For a long time, I'd have a TODO list for the day, and if I didn't finish items, I'd copy them to the next day's file. This was tedious, though at one point I created a script to make it easier. But worse: I discovered that the list would grow and grow, and lead to anxiety when I didn't finish them. (Occasionally, I'd toss items off the list, in recognition that I'd likely never do them.)
• Searching worked, but it was error prone. I'd often forget to make search case insensitive. Or the terms would return too many items. Because it was regular expression based searching, there was no way to say "find all files with this search term that also contain this other search term, but not necessarily in any proximity to each other."
• It was great while I was on a computer, but next to impossible to use on a mobile or tablet. As such, I tended to use it for work or for organizing programming projects, but not for the day-to-day. And there's a lot I want to be able to come back to, much of it when I'm not at my computer: recipes, lists of things to watch and read, art inspiration, shopping lists, and more. So having a file-based solution was not going to work.

I tried a few different things over time:

• Evernote. I actually used this for a couple of years, mainly to capture bookmarks, but cancelled it quite some time back (likely around 2017) when I realized I was getting locked into an ecosystem, and one that was increasingly moving away from how I actually wanted to use it. And the fact that it didn't really allow linking between notes, or have a vim mode made it something I wouldn't open regularly.
• Google Keep. This was installed by default on my Android phone, and the data went with me... but it was difficult to use it on the computer, and the search for it was really spotty, which was surprising for a company that started as a search engine.
• Nextcloud Notes. When I started using this, I imported my markdown files... and my instance was too underpowered to handle the sheer volume of notes I had. On top of that, once I got the notes imported to Nextcloud, the Android app would choke trying to sync, and was super slow when I would try to use it. And search... was not great.
• Joplin. This is an open source app that works on top of either Nextcloud Notes, or just on a filesystem. Again, I struggled with the sheer number of notes I had, and the fact that I couldn't use it on mobile made it not a great fit for me.
• nb. Somebody on Mastodon recommended this a little over a year ago, and I dove in as it was just markdown, vim, and the CLI. While it's text centric, it also has things like search and todo lists and more... but this was also it's hugest limitation: I couldn't feasibly use it on my phone or from my tablet. On top of that, the way that lists worked, and the fact that if you wanted project-specific lists you essentially had to have separate collections, meant that I stuggled to use it regularly or stick with it.

I've basically limped along, hopping from one solution to the next, without fully settling on any due to limitations.

What is Logseq?

Logseq is a Personal Knowledge Manager (PKM) application. PKM tools provide a way to collect information, and, more importantly, surface it. There's been a proliferation of these tools in the past years; you may have heard of Obsidian, Notion, and SimpleNote. But the idea is not new; things like Org Mode for emacs have existed for ages, and some PKM ideas derive from the Zettelkasten method.

Logseq itself is an open source application, built using Node and running in Electron; as such, it's cross-platform (I've used it on Linux, Android, iOS, and Windows). It stores the actual content as Markdown, though it uses tabs instead of spaces for indentation, and every line is a bullet point (more on this later). Because it uses local file storage, you can use git to version files and sync between systems, or you can use any file syncing you have available. (I've used Syncthing, Nextcloud, and even OneDrive at work.) The project rolled out a beta of a sync-as-a-service offering this past year, but I appreciate that it's not necessary or required in the least in order to use it.

How does Logseq work?

I started using this in late December or January of this past year, and was quickly surprised by what it enabled.

Let me explain.

When you open Logseq, you start in the Journal. This is a daily record, and once the day rolls over, it starts a new one. 99% of my work is done in the journal, and this is fantastic. It allows me to understand when I learned something, had a meeting, or recorded a task. While you can create separate pages, most of the stuff I want to track is relatively ephemeral.

Next, you can tag pages. Let's say I'm writing a note, and it's related to PHP; I can type #php, and this becomes a link. If I click that link, it takes me to the page — which may or may not exist. But even if it does not exist, it will reference all the pages that link to it. This is a cheap and easy way to organize things, and if I later want to add notes specific to that page, I can; it then becomes a first-class page in the system.

Tags are done as metadata, and metadata can be applied at the page level or item level. Some, like tags:: {tag list} and due:: {date} are special to the system, and will surface functionality. But they can be anything. I've used them to be able to note page or item types, people I have meetings with (which I link to the pages for each person), and more.

You can also create templates. These are text snippets that you want to re-use. As examples, for work, I created templates for meetings (to allow me to indicate who the meeting was with, when it happened, the agenda, any notes I took, and any action items from it), and for weekly prioritization (more on that later). At home, I created templates for bookmarks (so I could give information on why I found the bookmark useful, the title of the page, and related tags), and recipes (so I could tag the type of food, specific ingredients, etc.).

Tagging pages makes it easy to search. I can search, and if there's a page matching the keyword, I can go to it and immediately see what other notes I've taken on that subject. Even better, though, Logseq includes both some basic search functionality that allows selecting for things like tags/pages, attributes (such as whether or not something is a task), and free text, and this can be done within the page itself, allowing you to see what matches immediately.

You can also create slash functions that pull in templates or evaluate to text. An example I use frequently is one I installed from the Logseq marketplace, which creates a search for tasks completed in the past week.

All of this brings me to another cool feature. I noted in the description of Logseq that each line in a page is a bullet point. Logseq creates hashes for each of these, which allows referencing them.

This means you can:

• Link to any page or item in a page.
• Embed items anywhere. To do this, you right click on the bullet for the item, which allows you to copy a block embed; you then paste this in another page, and you see the content right there, and can even manipulate it from there!

Because of all this functionality, Logseq surfaces relevant information when you need it.

Did you schedule something in the future? If so, the Journal will show you upcoming scheduled items — not all of them, but the ones coming up soon (which you can define in the configuration). You can create Journal pages for dates in the future, and if they include todo items... those will show up on the Journal as well, so you can remember. I often create Journal pages ahead of time to create agendas for my one-on-ones; this ensures that those fleeting thoughts of "I should ask them about so-and-so" don't get forgotten when the day of the meeting rolls around.

How do I use Logseq?

Prioritization

My prioritization template for work brings in two search queries, one for pages with a project type that are incomplete, another for incomplete tasks that are not part of a project, which represents my backlog. This allows me to go through each week and identify what on the backlog I can and/or should work on in the coming week, cancel tasks I recognize I will no longer do or which are no longer relevant, mark things as done that I may have completed this past week without realizing a task existed, and so on.

What I do is go through these items, and choose what I want to work on. I then embed those items into the page for that week, which gives me a list without duplication, and which I can then reference later when I'm wanting to understand what I did that week. I often also schedule items at that time, to ensure they surface on my journal pages.

At the end of the week, I run the query to show what I completed the past week on that prioritization page. This gives me an excellent reference of what I actually did — which is often far more than I'd planned on for the week! Often, if I find I did not finish what I set out to do that week, I can tell at a glance why: an unexpected request from my GM, a request from marketing, additional customer calls, etc.

These features have allowed me to be more intentional in my interactions with co-workers, ensure I'm more accountable to myself and to others in ensuring I get work done, and allow me to be better organized.

Home cookbook

I've tried a number of solutions for recipes in the past, including building my own apps.

The problem is (a) maintaining those apps, and (b) being able to find recipes when I need them.

For my personal Logseq instance, I created a template for recipes so that they are in a common structure, and that template includes metadata and tags so I can (a) find the original source if I need it, and (b) search for recipes by ingredients I commonly might have on hand.

I've got everything in it from recipes and tips for salting, brining, and seasoning, to main dishes, to cocktails.

Want to do a Rum-based cocktail? Search for (and [[rum]] [[cocktail]]). Need the instructions for brining and roasting the annual turkey? Search for "turkey".

It's been magical.

Weekend projects and household todos

I often know that I need to do something around the house, but forget by the time the weekend arrives. I now create these as tasks in Logseq, with the tag "weekend". I can surface them quickly, and even use the ability to embed links to items to create a todo list for the weekend!

Final words

Would I recommend Logseq?

Wholeheartedly!

Look, it's not perfect. The Markdown it uses is tab-delimited, and each line is a bullet point, which makes using it to draft blog posts or other Markdown a bit of a pain. (I'm planning to write a tool to convert to standard Markdown over my holiday break, though!) But it is Markdown, and it even supports things like blockquotes and fenced code blocks and tables, which gives a wealth of ways to format text.

On top of that, it has a rich plugin architecture and ecosystem. You can do whiteboards, embed drawing widgets (I created an architectural diagram I shared with my engineering team using one of these!), create Kanban boards, or even use it as a full-featured calendar. One I use extensively is a plugin giving Vim bindings, which allows me to move around and edit in ways that are relatively familiar. If I absolutely have to, I can edit the files by hand (though with the slight differences in Markdown, this can sometimes introduce issues).

The fact that it is open source also means I can use it in perpeituity, so long as I am able to compile it and/or find an Electron version it works with. And because it's using plain text and SQLite under the hood, I can take the data and use it however I want.

Is it the right tool for you? I don't know. I think the important thing is to try one of these tools and stick with it. More and more functionality and content surfaces for me the longer I use the tool, and this is true of any good tool, I've found. (I'm still learning things in vim to this day, and it's been 23 years of use to me!)

Advent 2023: Logseq was originally published 1 December 2023 on https://mwop.net by Matthew Weier O'Phinney.

Vim is also my chosen productivity suite. When I want to write a document, I don't go into OO.o Writer or MS Word or some other word processor; I open up a window and start typing. In most cases, I can either cut and paste my work into other tools, or pipe it to transformation tools. I worry about the content first, and the presentation later… like any good MVC application. ;-)

Like any good tool, you have to invest time in it in order to reap its benefits. My learning has, to date, fallen into three time periods:

• The initial months in which I first learned Vim, via vimtutor and Steve Oualline's Vim book.
• A period in 2006-2007 when I felt the need to make my coding more efficient, and first started playing with exuberant-ctags and omni-completion.
• The last quarter of 2010 (yes, that's now) when I was introduced to a number of new tools via Twitter.

So, this is my Vim Toolbox, 2010 edition.

Getting Plugins

I've added two primary ways to add new plugins to my arsenal:

• Vimana, which is a command-line tool for discovering, downloading, installing, and upgrading scripts found on vim.org. It's not perfect, but if you know the name of the script, and it's provided in either a vimball format and/or follows the Vim runtime file structure, it's a great way to keep your plugins, syntax files, etc. up-to-date.

• Vim Pathogen allows you to install plugins as "bundles", allowing you to keep them up-to-date separately, in their own file tree. This looks like the following:

  .vim/
      bundle/
          vim-task/
              ftdetect/
              ftplugin/
              syntax/
  

  In short, a "bundle" mimics the structure of a Vim directory.

The latter, Pathogen, is my preferred installation method of choice at this point. Why? One acronym: DVCS.

A ton of popular Vim plugins are now being either developed or mirrored on GitHub or other DVCS sites. This allows you to clone them and then create a branch that's specific to your configuration. As an example, the popular snipMate plugin has its key-bindings hard-coded — which causes problems if you're already using those bindings. Which, if you're using any form of omni-completion, is all too likely. I simply cloned the snipMate repo, and created a branch for my configuration (I use <Leader><tab> to invoke it).

Now, it gets even better: I've made a git repository for my Vim configuration; with judicious use of git submodule, I can now add pathogen bundles as submodules of my repository. Right now, I've got bundles for html5.vim, mustache.vim, NErdtree, snipMate, TagList, vim-fugitive, vim-task, and vimwiki. This keeps my repository lean, while retaining the features I need and use daily.

As part of creating my Vim configuration repository, I also made a few changes to facilitate the process. First, I moved $HOME/.vimrc to $HOME/.vim/vimrc, and symlinked the former to the latter. This allows me to keep all my Vim configuration in one place.

Next, I moved my Vim view files outside the directory; this data is volatile and constantly changing, and really does not need to be versioned. These are now in my $HOME/.vim.view/ directory. Finally, I moved my tag files into a new $HOME/.vim.tags/ directory. More on that later, but, again, the rationale is that this data is volatile and does not need to be versioned.

DVCS

I mentioned I created a Git repository for my Vim configuration. In part, this is due to the fact that I'm proficient with Git — I use it day-in, day-out. Hg and other DVCS systems are also great; I'm not using them nearly as often, however.

To that end, I'm now using vim-fugitive. The author boasts that it's "a Git wrapper so awesome, it should be illegal"; I wouldn't necessarily go that far, but I do find it incredibly useful. While I'm typically working in a console, I also find myself in GVim windows regularly as well — and having a nice, familiar interface to Git is very useful. If you use both Vim and Git, I highly recommend checking out vim-fugitive.

Filesystem Navigation and Projects

At some point, unless you're one of those developers who likes to code everything in a single file, you need to do some sort of navigation. A couple years back, Andrei Zmievski introduced me to NErdtree, a dead-simple, colorized navigation. I use this every. single. day.

I also use a tool called Project. This tool allows you to specify "files of interest" to a project — either by automatically scanning a tree, or manually. Additionally, the way you specify the hierarchy can be entirely arbitrary — allowing you to flatten the tree when it's getting in the way. I use this tool regularly as well, though not quite as much as NErdtree.

Navigating Code

One often touted feature of modern IDEs is code completion and hinting. These are definitely useful features, particularly when working on unfamiliar code, or code you haven't touched in some time.

Vim actually has some great tools for this already. One is built-in: omni-completion (:he new-omni-completion for Vim's help on the feature). By default, it inspects the files in open buffers to provide completion (assuming it has a definition for that language and/or syntax highlighting) — but it can also utilize tag files.

The built-in omni-completion for PHP is reasonable — you can jump around by class names, function/method names, variables, etc. It gets much, much more useful, however, when you utilize tag files, as you don't need the files already open in order to get completion. I've blogged about ctags before; however, I've updated my scripts a bit.

First, exuberant-ctags is much more PHP aware now than when I blogged. This means you don't need to do any special regex-fu in order to properly identify abstract classes, interfaces, and methods. Second, I found that I could generate a single script with prompts to indicate the directory and tag file name. That script basically looks like this:

#!/bin/sh
dir=""
name=""
if [ $# -ge 2 ] ; then
    # Two arguments: first is directory, second is "alias"
    dir=$1
    name=$2
else
    if [ $# -eq 1 ] ; then
        # One argument: use as directory, and use basename of directory as alias
        dir=$1
        name=`basename $1`
    else
        # Otherwise: prompt
        echo "Enter the path to a directory containing PHP code you wish"
        echo "to create tags for:"
        read dir
        echo "Enter the name of the tagfile you wish to create:"
        read name
    fi
fi

echo "Creating tags for directory '$dir' using alias '$name'"
cd $dir
exec ctags-exuberant -f ~/.vim.tags/$name \
-h ".php" -R \
--exclude="\.svn" \
--totals=yes \
--tag-relative=yes \
--fields=+afkst \
--PHP-kinds=+cf 
echo "[DONE]"

Two things to note:

• It creates the tag files in $HOME/.vim.tags/. I do this as my tag files change fairly regularly, and can be re-generated on the fly as needed. There's no reason to version them.
• Once generated, you need to load them. I created a "LoadTags" Vim function that will load a tag file by the given name from the $HOME/.vim.tags/ directory. By default, I load the ones I most commonly use (ZF1, ZF2, PHPUnit). Otherwise, a quick :Ltag <tag filename> will load on-demand.

Once the tags are created, you can use Vim's normal tag features to load files, jump to files, etc. The most common commands I use are:

• :stag <tagname>, which splits the current window and loads the given tag in the newly created split.
• <Ctrl-w>], when on text you suspect of being a tag (such as a classname), will split the current window and load that tag file in the new pane.

These two commands I use constantly, and are huge timesavers — I can basically use the code as my documentation.

Additionally, the main use of omni-completion is to give tab-completion for known tags. This means that you can start typing, hit <Tab>, and either have it immediately complete, or give you a list of potential matches. It's not quite as useful as a good IDE — it's not context-aware, so you'll get any potential match from any class — but it's better than nothing, provides reasonable hinting, and helps protect you from spelling errors.

That said, there's also something to be said about just having the signatures and prototypes of the various methods easily accessible. For that, there's the Vim TagList plugin. This plugin will scan open files and produce a list of classes, variables, and methods. With this list, you can get the method prototypes, as well as jump directly to their definitions. Pressing <Space> will show you the prototype, <CR> will jump to it.

Between these two features (omni-completion with tags and TagList), I have most of the useful features of any IDE immediately available.

Working With Code

Since I sling code for a living, it's useful to have some plugins and syntax highlighting to make working with code easier.

First off, I've been experimenting with HTML5; as such, I added the html5.vim syntax highlighting as a Pathogen module. This adds support for a bunch of HTML5-specific features, while retaining the fantastic HTML support already in the official HTML syntax provided with Vim.

Next, I use the php.vim syntax file from vim.org. This particular syntax file has support for PHP 5.3 features, which come in very handy while I'm coding for ZF2. The author of this syntax has also created a script (php_vimgen.php) for generating syntax files for core classes as well as extensions using the Reflection API. I've modified the tool in my repository to strip out the generated syntax, and instead source it from the file created with the php_vimgen.php script; I've also altered said script to create the syntax in __DIR__ . '/php_syntax_vimgen.vim', ensuring I can always source it from the same location. This allows me to keep my PHP syntax highlighting up-to-date.

Finally, I use snipMate, a tool that emulates TextMate's "snippet" features. Basically, this is dead-simple, templated code generation. You can write your own files (I did), or use those that come with it. Once you've got some snippets, you type a word (usually a mnemonic for the operation you're trying to perform), and it will either just spit up a template, or optionally provide "prompts" for you to fill in (along with variable completion!). Basically, I never code accessors and mutators anymore; snipMate does these for me, with a little prompting.

Organization

I use Vim day-in, day-out, for all sorts of things: mail, drafting blog posts, drafting presentation outlines, taking meeting notes, managing my todo list, and more. As such, I try to keep as much of my "organization" within Vim — it's just easier.

I've tried a number of tools over the years. For a good 4 or 5 years, my primary tool was VimOutliner. It provided decent syntax, decent folding, and reasonable HTML generation from the outline. However, in recent years, I feel the project had stalled, and I also found that the way I wanted to use it had changed: outlining is great, but I often want to use the outline as a starting point for generating content; task tracking is fine, but I found, for whatever reason, that the way VimOutliner handled task status often didn't work well — either from a tooling or a syntax standpoint.

At some point, Travis Swicegood introduced me to vimwiki. This tool provides a personal wiki within Vim. This tool allowed me to organize my notes in an ad-hoc, semi-hierarchical way, link back and forth between them, and have not only reasonable in-editor highlighting, but great HTML generation. This allowed me to ditch VimOutliner for everything but task tracking. Once I made my "wiki" directory a Git repository, I then received versioning basically for free (especially with vim-fugitive, which makes it easy for me to hit :Gwrite and :Gcommit when I create and/or update files).

Another feature vimwiki provides is a "diary". You access it using <Leader>w<Leader>w, which opens up a new wiki page for the current day (or, if you already opened it before, re-opens the one created earlier in the day). This is a really useful tool for taking notes during meetings, or when doing research, etc.

Couple these features with integrated search (:VWS /pattern/), and vimwiki is the killer productivity tool in my toolbox.

At another point, Travis then pointed out another tool: vim-task. This is perhaps the most dead-simple task tracker I've ever used; each line is a task, and is either incomplete (starts with a "-"), or complete (starts with a checkmark). A simple keybinding, which I've mapped to <Leader>m, toggles status - and complete items get highlighted in green and italicized, making you feel good and giving a good visual queue as to what you've completed.

At some point, Travis also tossed out the idea that combining vimwiki with vim-task would be useful — and I latched onto this idea. I've now created a fork of vimwiki with vim-task integration, which allows me to keep my tasks and notes in a single place… and, since my wiki is versioned, my tasks are as well.

Various Oddities

As I mentioned at the start of this post, I've been using Vim for close to a decade. Part of the reason Vim was appealing to me was due to the fact that it kept me in the "home row" of the keyboard — which provides a huge amount of efficency. You don't have to move to the arrow keys to scroll, no leaving the keyboard for the mouse, etc. That said, some key combinations are difficult to reach:

• The placement of the <Esc> key varies from keyboard to keyboard, and is rarely in a place that is easy to reach. On my current keyboard, it's in the top left corner, above the function keys; it's impossible to reach without moving my hand. A tip I picked up pretty much when I began using Vim was to map jj to <Esc>; it's rare to type a j repeatedly in the English language, and it's dead-center on the home row. This is incredibly efficent.
• I've mapped my Caps Lock key to <Ctrl> on every system I've owned in the past decade. I never used it, and it's almst always on the home row. Again, hugely efficient.
• Keybindings are great, but there's so many already in use that it's hard not to overwrite existing ones. Using the <Leader> key to define keybindings has been great. As examples, I mapped <Leader>m to toggle tasks, and <Leader><Tab> to invoke snipMate.

In Vim, <C-m> has long been the "make" binding, and <C-l> for linters. In languages like PHP and JavaScript, these often don't make sense. However, I've bound these in both languages — in PHP, "make" executes the current script using the PHP executable, while "lint" runs it through the PHP linter. In JS, I leave "make" unbound, while "lint" runs the script through jslint.

I've also added the "php-doc.vim" plugin, and mapped <C-P> to create PHP docblocks; the plugin is context aware, and will create appropriate annotations.

Cloning my repo

As noted, I've created a repository for my Vim configuration. If you want to clone it and explore it, you can do so as follows:

• Browse the repository: http://git.mwop.net/?a=summary&p=vimrc
• Clone the repo: git clone git://mwop.net/vimrc.git

Be aware that there a number of git submodules in play (all the pathogen modules are git submodules). To initialize these, simply run git submodule init followed by git submodule update after you clone the repository.

Resources

I didn't learn all this overnight. As with any toolset, it's only as good as the amount of time you invest learning it. For me, my primary resources lately have been:

• #vim hashtag on Twitter
• VimCasts are a fantastic source of information, provided by Drew Neil. Seriously, these are completely worth the time spent watching them.
• Travis Swicegood has tweeted a number of times about interesting things he does with Vim and Git, and inspired me to write the vim-task syntax for vimwiki.

More Tools

This post has been on my Vim toolbox. I've also been usig a number of other tools lately — tmux, zsh (in particular, git prompts), Hotot (GTK2 + WebKit Twitter client), and more; I may blog about those in the future — using Vim. ;-)

Vim Toolbox, 2010 Edition was originally published 15 December 2010 on https://mwop.net by Matthew Weier O'Phinney.

The funny thing is that Textmate is a newcomer, and, of course, vim has had such a feature for years. The thing to remember with vim, of course, is its unix roots; typically if you know the unix command for doing something, you can find what you need in vim. In this case, the key is the vimgrep plugin, which ships in the standard vim distribution.

There are a variety of resources on vimgrep. The vim documentation includes a chapter on it, and a quick google search on the subject turns up some nice tutorials immediately. If you've ever used grep, the syntax is very straightforward:

vimgrep /{pattern}/[g][j] {file} ...

The "g" option indicates that all matches for a search will be returned instead of just one per line, and the "j" option tells vim not to jump to the first match automatically. What does the "g" flag really mean, though, and how are searches returned?

Vimgrep returns search results in what's known as a "quickfix" window, and this is where the vimgrep documentation falls apart… it doesn't explain what this is, or link to it (which would be a nice indication that it actually has a separate topic for this).

The Quickfix window is a pane that shows a search result per line. Each line shows the file that matches, the line number, and the contents of that line:

/home/matthew/git/bugapp/application/controllers/helpers/GetForm.php|10| * @var Zend_Loader_PluginLoader

You can't do much from this window; it simply serves as a visual indicator of what file you're currently looking at from the list. However, in the main window, you can start iterating through the results one at a time, using a subset of the Quickfix commands. As a quick summary:

• :cc will move to the next match in the list
• :cn will move to the next match in the list
• :cp will move to the previous match in the list
• :cr will rewind to the first match in the list
• :cla will fast forward to the last match in the list

When done, you can simply close the Quickfix window/pane, and continue working.

I should note that vimgrep is cross-platform. On *nix-based systems, it defaults to using the native grep command, but it also contains an internal (slower) implementation for use on operating systems that do not provide grep by default. You may also map the command to alternate implementations if desired.

I personally use this feature most with the project plugin. Project maps vimgrep to two different commands: <Leader>g and <Leader>G. The first will grep all files in the current project at the current level; the second does the same, but also recurses into subprojects. This is an incredibly easy way to refactor code, particularly for name changes.

Vimgrep and Vim Project was originally published 21 October 2008 on https://mwop.net by Matthew Weier O'Phinney.

Mapping the PHP interpreter and linter to keystrokes

Probably the most useful thing I've done as a PHP developer is to add mappings to run the current file through (a) the PHP interpreter (using Ctrl-M), and (b) the PHP interpreter's linter (using Ctrl-L). These are accomplished with the following:

" run file with PHP CLI (CTRL-M)
:autocmd FileType php noremap <C-M> :w!<CR>:!$HOME/bin/php %<CR>

" PHP parser check (CTRL-L)
:autocmd FileType php noremap <C-L> :!$HOME/bin/php -l %<CR>

(I have \~/bin/php as my PHP interpreter, which allows me to run PHP with a custom config file, as well as to change which PHP binary I'm using.)

These two commands allow me to quickly and easily check that my syntax is okay, as well as to run unit test suites easily.

Vim Project

Next up is the excellent Project plugin.

"Project", at its most basic, allows you to setup a navigation pane with a list of files related to your project. The files are typically organized by directory, but the beauty is that the hierarchy can be defined however it makes sense for your given project. It also has tools for creating projects based on a given directory, recursively pulling in files based on filters you specify. Type :help project to get documentation on this after you install it; \C will help you create your first project.

Each project can consist of one or more project folds; these can be sub projects, or a self-defined hierarchy or grouping of files. For instance, in my Zend Framework project file, I have "library", "tests", and "documentation" folds — "library" points to "library/Zend/", "tests" points to "tests/", and "documentation" points to "documentation/manual/en/". Within each, I then have folds for each subdirectory. Since directories and subprojects are specified as folds, you can use Vim's native folding mechanisms to keep only the file of interest visible, which is very handy.

Basically, Project allows vim to act like a minimal IDE. With the file list on the left, you simply hit enter on a file, and it loads in the main pane. More fun is when you use the \S command, which will split the main pane and load the file into the new pane. This is particularly useful when doing Test Driven Development, as you can have one pane for the unit test code, and another for the class file, allowing you to jump back and forth between them. Add to this the Ctrl-M and Ctrl-L commands I listed earlier, and you're now also able to quickly and easily check your files for syntax errors and run tests directly within the Vim window.

There are other commands, too. You can run all files through a particular script, grep all files in a project, map particular file types to specific launchers, etc. Combine it with other Vim functionality, and you have a minimal, yet powerful, IDE at your disposal that launches in under a second.

By default, Project stores projects in $HOME/.vimprojects. I find that I don't necessarily want all my projects at any given time, so I've created a $HOME/.projects/ directory that has a project entry for each project — I simply save the contents of a project fold to files under this tree. I can then perform :r ~/.projects/<projectname> to read in a given project when I want to work on it. This helps me keep my workspace uncluttered, and also helps me focus on a given project at a time.

Ctags

I've covered ctags elsewhere, so I won't cover them here, but with ctags defined, I get tab completion for most classes and methods (and Vim takes care of tab-completion for class members in the current class file), as well as the ability to quickly and easily open class files for classes I've tagged — which is useful when you want to see what methods are available and how they work.

I'll try and cover other vim techniques I use in upcoming blog entries. Those listed in here, though, have greatly increased my productivity, and are things I use daily.

Vim Productivity Tips for PHP Developers was originally published 22 March 2008 on https://mwop.net by Matthew Weier O'Phinney.

One way I get around it is by adopting PEAR coding standards for naming my classes. Since they define a one-to-one mapping of class name to the file system (substitute the underscore character (_) with the directory separator), I can usually very quickly and easily open a class file, particularly if I start in the base directory of the project install.

Today, however, I found exuberant ctags, a library which can be used to generate an index file mapping language objects to source files and the line in the source file where they are declared. Contrary to its name, it's not just for the C language; it currently supports 33 different programming languages, including PHP.

I decided to try it out on the Zend Framework core library today. At first run, it was pretty useful. However, it was only mapping classes, and, in addition, only those defined with the single word 'class' — abstract classes and interfaces were entirely left out. So, I looked into the documentation to see if I could change the behaviour.

And, being a Unix program, of course I could. First off, you can add functions to the items it indexes with a simple flag. Additionally, you can use POSIX regular expressions to refine what it searches.

I whipped up the following script to create my tags index:

#!/bin/bash
cd /path/to/framework/library
exec ctags-exuberant -f ~/.vim/mytags/framework \
-h \".php\" -R \
--exclude=\"\.svn\" \
--totals=yes \
--tag-relative=yes \
--PHP-kinds=+cf \
--regex-PHP='/abstract class ([^ ]*)/
/c/' \
--regex-PHP='/interface ([^ ]*)/
/c/' \
--regex-PHP='/(public |static |abstract |protected |private )+function ([^ (]*)//f/'

This script creates the tag index in the file $HOME/.vim/mytags/framework. It scans for PHP files recursively through the tree, excluding any files found in a .svn directory (I'm using a checkout from the subversion repository). The file paths in the index are created relative to the tags file; this was important, because if this wasn't provided, vim was unable to jump to the file, as it couldn't find it. --PHP-kinds=+cf tells it to index classes and functions. Next, I've got three regular expressions. The first tells it to match classes beginning with 'abstract class' as classes. The second tells it to match interfaces as classes. The last is so that PHP 5 methods, which begin with a visibility operator, to be matched as functions.

Once the index file is generated (it takes less than a second), all you need to do in vim is tell it to load it: :set tags=~/.vim/mytags/framework. At this point, you can do all sorts of fun stuff. Place the cursor on a class name or method name, anywhere in it, and hit Ctrl-], and you'll jump to the file and line of its declaration; Ctrl-T then takes you back. If you change the invocation to Ctrl-W ], it will split the current window and open the declaration in the new pane. (If you're familiar with how help works with Vim, this should seem pretty familiar.)

One more reason to stick with Vim for your PHP editing needs. :-)

exuberant ctags with PHP in Vim was originally published 31 January 2007 on https://mwop.net by Matthew Weier O'Phinney.