I work on my dotfiles periodically throughout my day work or non work related (that bonsai tree that's never done). I've written a couple of markdown documents that have become rather large to navigate in vim and for the most part i just go to the top of the document using gg in command mode to search for what it is i'm looking for. it works a portion of the time, but it'd be ideal if i could navigate a markdown document .md using universal-ctags as most of the documents i work with have a TOC within them, so popping open the TOC within the document and doing a ctrl+] to go to the heading under my cursor could become super useful for navigating my markdown documents, (a local wiki of notes i maintain for referencing tips tricks and howto's throughout my day).

universal-ctags comes with some regex matching for .md (Markdown) documents out of the box, and i can navigate to a heading that does not have spaces in it.

Example: markdown document structure


<a id="contents"></a>

## Contents

 - [Gotchas](#git-gotchas)
 - [Useful Links](#useful-links)

I move the cursor under [Gotchas] and i'm able to move to that particular position in the document using ctags, but if i try to navigate to the [Useful Links] section of the document it's a no go as I'm pretty sure uctags is running into an issue with the heading containing a space within it.

I literally was able to get ctags installed just a few days, and, that was a completely separate issue upon itself, but i do have uctags installed and working now, but have no idea how it uses regex's to aid in the generation of a tags file for a particular project / repo.

Obviously the more information one could provide the better it would be in helping understand what is going on, as I've tried a couple of different regex examples on the internet, and they seem to fail, either in building the tags file due to a syntax error thus preventing a tags file being generated at all, or they fail in navigating through headings that contain spaces in them, ie. Useful Links

  • What about loading the headers into a quickfix list or interactive menu?
    – D. Ben Knoble
    Commented Feb 14, 2020 at 5:10

1 Answer 1


A simple approach (that fails if you have embedded code comments) is to do something like


And then type : and the displayed line number of the match you want. You could assign the commands to a mapping.

Or, yank the words you want to search and do /^#\+ <C-r>", which could be assigned to an operator for fun: e.g., ghi] would take you to the header matching for the words im brackets.

  • please excuse my ignorance, I'm new to ctags and your answer comes across as abstract to me. Is this a Vim only solution? or is this incorporating ctags? And if either is the case? I don't suppose you could put together a visual explanation of your answer by creating an asciicast?
    – ipatch
    Commented Feb 19, 2020 at 17:10
  • @ipatch im not sure when I’ll have to put together a video, but yes these are just vim commands. I can try to expand a little later at some point.
    – D. Ben Knoble
    Commented Feb 19, 2020 at 19:49
  • ahhh yeah, that's what i figured, was / am hoping to setup a ctags based regular expression for navigating markdown documents.
    – ipatch
    Commented Feb 19, 2020 at 20:39

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.