Submitted by annikastheory in vim (edited )

What-do

Just a brief summary of what this lets us do before I go explaining everything. I type school papers in markdown. I use zotero to manage my bibliography. If we output the bibliography to bibtex and keep it in the same folder as the paper we can get auto-completion for our citations. Likewise if we create a tags file and keep it in that folder we can do :ts / and hit enter to get a table of contents for the file, and quickly navigate to a heading.

How-to

I am going to write how to do it before explaining how it works and why I do it this way.

First you need to make sure that you have the "universal ctags" program, as this one supports many languages (as opposed to only C). On some linux distros this is the default. a quick check would be to run ctags --list-languages If you get a long list of languages you are probably good to go.

The citation auto-completion assumes that you have the bibtex file for your citations in a folder with your markdown document. So if you use zotero or whatever export your citations for the paper into a bibtex file and place it in the folder. Now with that done run this command in the project folder

ctags --languages=markdown,bibtex --sort=no *

Now open the markdown document in vim. If you do :ts / and hit enter you should see a list of all the headings in your markdown document. It will number each one and if you enter the number and hit enter you will jump to that heading. We can also search heading this way by doing :ts/foo for example.

Next try to enter a citation into your markdown document. Citations are usually formatted at the end of the sentence like this[@author_title_date]. In insert mode type the[@ plus part of the authors last name and then type <C-x><C-]>. And there you have autocompletion of your citation.

If you want that ctags command to run often you could create a vim mapping or autocommand to run it as well.

How-do

For the uninitiated Ctags is a program originally for making a tags file for the C programming language. Tags are essentially the names of each function with their locations within a program. So if you have a function in your program called Foo the tags file will tell you which file, or files, its in and where in that file the function is located.

What is super helpful for us is that Vim by default makes use of the tags file. As mentioned above universal ctags program extends this functionality to a rather large amount of other languages. For our purposes the relevant languages are bibtex and markdown. But of course you could use it with say python or something and it would be super useful.

In this case ctags treats the headings in markdown as a tag and reflects that in the tag file. Likewise it treats the citation entries as tags as well which allows us to use the command to autocomplete a tag <C-x><C-]> in insert mode. If you are wondering why I put citations into a markdown file you can use pandoc to convert the markdown to doc (or whatever) and automatically put the citations into whatever citation schema you need. (I may do this in another post)

Why-do

I'm pretty sure that if you can find a way to do things without plugins that when you die you go to vim heaven. But also there are plugins that do this but in my experience they suck, and are very very slow and freeze contstantly. This may take a little more set up the first time but it works very well and is fully integrated with vim.

Closing thoughts

My only complaint, and it is minor, is that the tags file will have both the bibliography and the headings so both tag types popup for completions. You could circumvent this by creating two tag files (one for markdown one for bibtex). You would then have to rename one of them using the -f flag in ctags. You would probably want some kind of mapping to toggle between the two tag files when you need too. I would do all that but it is a minor gripe anyhow.

If you are interested in another markdown related ctags usage check out this in which the person set up ctags to allow wiki-like tags in his note taking system (I use a somewhat similar set up for my notes).

4

Comments

You must log in or register to comment.

emoticons wrote

this a neat vim and bibliography markdown tags. good guide and list help plugin I am vim simple :)

4