Feature: Insert Internal Links With Completion

[hmelman]

I saw this http://pragmaticemacs.com/emacs/insert-internal-org-mode-links-the-ivy-way/ and wondered if it would be a useful idea for markdown-mode.

My thought was an easy way to make internal links like #Heading1 or any other ids defined in the document using completion. I'm not sure markdown-mode knows the format of generated ids for headings that the markdown-command will use, but maybe that's standard or some substitute could be used. Bonus points if clicking on the link would move point to the referenced location in the document.

This code unfortunately uses a worf function but it could depend on just org-heading-components which I'm not sure markdown-mode has a direct equivalent of (it must come close since imenu works though I realize buffer positions and named anchors or ids are different).

I typically just insert links like [text](url) via a function that grabs the current url of my browser. In investigating this idea I looked at the various markdown-mode link commands and got confused. Maybe this is just what markdown-insert-wiki-link is for and I'm just asking for a version of that command with completion. I looked at the menu and tried Insert Wiki Link. After typing C-c C-a, which-mode showed me six commands bound to that prefix though only two are shown in the menu. I saw that markdown-insert-reference-link-dwim had two bindings but was obsolete. That was fine and it told me to use markdown-insert-link instead but I wondered why that had no key binding and the obsolete function had two.

[jrblevin]

Thanks for this suggestion.

As you mentioned, the variation in implementation details across different Markdown processors is an issue, but I could probably handle that by letting users set a customizable heading-to-anchor-id transformation function. It's made more difficult because some processors allow using inline attribute lists to define the id, but markdown-mode also doesn't handle those yet.

Regarding the confusion about multiple link functions: the link functions and keybindings are somewhat in flux right now ahead of v2.3. In light of the new markup/url hiding functionality, I have added the new function markdown-insert-link on a more prominent binding, C-c C-l. It handles what were previously three different functions (markdown-insert-{inline, reference}-link-dwim and markdown-insert-uri. This function can be used to insert or edit any one of those three kinds of links, depending on which prompts are completed. Soon I'll be doing the same for inline and reference images.

Currently, insertion commands are scattered around under C-c C-a, C-c C-s, C-c C-t, and elsewhere. Those are remnants from html-helper-mode, which I used as inspiration for the keybindings at the time. It seems less compelling now to link the keybindings to HTML tag names (a for anchor, e for <em>) , so I will also be consolidating the insertion commands under one prefix and adding a minibuffer hint for the final key after the prefix is entered (even I sometimes forget the keys). So, bear with me on the keybindings in the short term and I think they'll make more sense and be more memorable in the long run. (Also, for the possible later benefit of myself and others, I should note that this is all also related to #199 and #206.)

[hmelman]

Thanks, that all sounds good. I'll just say that wherever possible, please use completing-read with a collection and then things like ivy, helm, ido will make entering info very easy. Looks like you're doing this in some places already.

If you're changing key bindings, let me say, I hate the prefix C-c C-x. I know other modes use it (like org-mode), but for my taste, it's too similar to C-x C-c.

[jrblevin]

Great. Yes, I'm using completion for URLs, reference labels, etc. in the new link insertion/editing function (and am planning to add elsewhere as I go).

The plan is to move all markup insertion/replacement (styling) commands under C-c C-s, where some of them already live. I've been consolidating mode-type toggles under C-c C-x, but I don't plan to use it for common functions.

Edit: I'll also keep the old keybindings around for the next version or so, in cases where it's possible (almost all cases).

[VladimirAlexiev]

@jrblevin: The version I use (2.4-dev) has auto-completion for document headings (anchors) using C-c C-l Tab. If I select an anchor and click Enter for "link text", it inserts a plain URL like this, which doesn't work very well eg in gitlab preview:

<#intro>

It would be great if it also picked up the heading name and inserted a link like that:

[Intro](#intro)