A Keyboard Maestro macro for cross-linking Markdown docs

Ok, this is one of my other projects from last weekend. In its present state it has a more limited scope of appeal than my Howzit updates, but the idea could easily¹ be modified to work with any project that consists of a bunch of Markdown documents.

I designed this for use when working on my Jekyll-based documentation sites. Jekyll actually isn’t the important part, it just requires the files to have YAML headers with a title key, and any manually-specified header IDs to be in Kramdown’s format:

## My Title {#id}

If you were to change the handling of both of those requirements, any folder containing a bunch of Markdown files would work. The rest of the macro is all based on easily-configured templates.

Anyway, what it does is create a shortcut (lnk//) that, when typed, offers a spotlight-esque search through all of the other documents in the project (and the headlined sections they comprise), and when you choose one, it inserts a templated link to it relative to the project root, including a #fragment to link a specific headline.

The first time you run it, it will ask for your root directory and link template. The directory is a POSIX path, e.g. /Users/me/Sites/dev/bunch, and the link template allows placeholders in the format <path>. Available placeholders are:

• <path>: Full path from the DocsDir root (e.g. “/subdir/file”)
• <dir>: Directory portion of path (e.g. “/subdir”)
• <file>: Filename portion of path (e.g. “/file”)
• <frag>: Headline ID, empty if none (e.g. “#fragment”)

All extensions are removed from the paths, and all placeholders except for <ext> and <frag> have leading slashes (<frag> gets a leading #). So my template for the Bunch docs is:

<path>/<frag>

To change configuration later, type lnk\\ (with backslashes) and you’ll be able to enter a new directory and optionally change the template.

Now, just type lnk// in your Markdown document, type a few characters of the page you want to link to, hit return, and you have a correct link to the topic you wanted to reference.

That’s it. It’s pretty simple. It actually started off as a TextExpander snippet, but that would take a search string and insert the first matching document. The matching was a little more flexible, but I really liked Keyboard Maestro’s “Prompt with List” interface and the ability to refine a search on the fly. You have to put a space between search terms to represent path breaks, e.g. to match “docs/bunch-files/commands/awake” you would need a space where the slash goes: “comm awa” would find it.

There’s also a version included that works on selected text using a keyboard shortcut (defaults to ⌃⌥⇧L). It uses the selected text as the initial search, which can be hit and miss but is great for wiki-style linking. I mostly use the text-triggered one, though.