Creating tags between markdown files similar to :h

Question

One of the first things you learn in vimtutor is to follow links in the vim help files with Ctrl-]. I'm interested in creating my own tags/linking system in arbitrary files. For the sake of this question, let's say I'm creating a sort of TODO list in markdown.

Suppose that we have the following minifile:

TODO
=====
  1. Learn Vimscript the Hard Way    |hardway|

(some other things, maybe)


Complete Learn Vimscript the Hard Way
-------------------------------------  :hardway

(Some sort of details, etc.)

Then the goal would be to put the cursor on the first |hardway|, hit something akin to Ctrl-], and be transported to the :hardway tag located elsewhere. Ideally, this could even occur if :hardway was in a different file (but maybe the same directory).

I currently use a low-tech alternative. Instead of |hardway|, I would have something like |hardway.md|, so that I can gf on the "tag" and ge taken to the hardway.md file. While this is manageable, I feel like it should be possible (maybe even not hard) to create and maintain my own tag system on arbitrary filetypes.

Answer 1

I've implemented something like this using Exuberant Ctags and a .ctags file in the directory (should also work with .ctags in the home directory).

You can read up on using Ctags with arbitrary regex, but the gist of it is that you'll be able to use that same Ctrl-] to go to these tags.

The contents of my .ctags:

--langdef=markdown
--langmap=markdown:.md
--regex-markdown=/^#+\s*([^#]*)\s*#+$/\1/h,heading,headings/

Then run ctags.

ctags -R

And you should get a file called tags which has mappings for all markdown headers in the ### HEADER ### format.

See :help tags for more information about navigating tags (e.g. when there are multiple hits for a tag).

Answer 2

VIM's :find and gf are quite awesome, I use them all the time, they rely on the vim setting path and look for files in there. VIM also provides additional setting suffixesadd which is a list of suffixes find will try to add to the file names and look them up. eg.) set suffixesadd+='.md' to work with markdown files.