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 Feb 14 '20 at 5:10

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 Feb 19 '20 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 Feb 19 '20 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 Feb 19 '20 at 20:39

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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