RFC: Cross-Link Definition Formats

1

I’m working on an extension to the syntax definition format which I have previously requested feedback about. Start with that RFC if you have not read it. The ability to customize and extend Drafts with these definitions is coming later in 2020, but for now, I’m going to start shipping some enhancements to the default Markdown syntaxes that ship with the app supporting the ability to create cross-links between drafts and other resources with a simple wiki-style markup. If you are interested in how these are defined and will be able to be extended in the future, read the updated link definition information on the preliminary syntax definition docs page.

What Link Definitions Can Do

The link definitions create a way to find particular match strings in your document and make them clickable links with a URL attached to them.

Basic Link Format

The extensions to the Markdown Syntax planned are will follow the [[ ]] double-bracket style used in Wikis and a number of other notes apps, but have the slight twist that they will include a key and value in the format

[[key:value]]

The key will be used to determine the URL template to use for the link. The value can be dynamically inserted into the URL template to be a parameter in the URL.

Internal Drafts Link Types

The following keys are planned to support links within Drafts:

  • [[d:Title of Draft]]: This will create a clickable link with will open another draft with the specified title.
  • [[s:Search Term]]: Open quick search to “Search Term” query.
  • [[u:UUID-OF-DRAFT]]: For fixed link to a specific Draft by UUID.
  • [[w:Workspace Name]]: Open a named workspace.

Each of these, when typed in draft text, generates a link to a URL that uses Drafts URL schemes to actually navigate.

External Link Types

This format is not limited to URLs that are using the drafts: URL scheme. These definitions can support external URLs as well. I’m going to leave more extensive options out there for customizations later this year but will ship a couple of handy ones. Currently planned:

  • [[google:Search Term]]
  • [[wikipedia:Search Term]]
  • [[bear:Title of Bear Note]]

The first two open web searches, pretty self-explanatory. The bear: one takes advanced of Bear’s URL schemes which support lookup of a note by title. Not sure there are other apps that have URL schemes with that sort of deep linking.

Conclusion

Thoughts on these options and formats as defaults? Nothing is set in stone, just roughing things out.

4 Likes
2

This would be so useful.

Things also has an url scheme I use in some scripts. Would be great to plan it too ; it would considerably simplify the scripts. See https://culturedcode.com/things/support/articles/2803573/

3

DEVONthink Support :slight_smile:

1 Like
4

One way to support DEVONthink would be for something like [[dt:SEARCH TERM]] link to resolve to a x-devonthink://search?query=[SEARCH TERM]. It’d be nice if there were a way to link into a DT item with just a title, but I don’t see a way to do that given the URL scheme available.

5

A “back” and a “forward” button would be useful as well to navigate in-app linking.

2 Likes
6

I’ve been tinkering with these link types, going through my existing drafts and seeing how they make a difference to the drafts I’ve been regularly using (simplifying things and making them look much neater than the UUID linked drafts I had), and how they open up new possibilities. They’re working really well. I think these changes are great.

I’ve just noticed one new link type that would help me, which I’d love to have the ability to use—links to shortcuts.

I have a couple of drafts where I use markdown links of the form

[Shortcut Name](workflow://x-callback-url/run-workflow?name=Shortcut%20Name)

to have ready access to a shortcut in my draft. If that could be replaced by

[[shortcut:Shortcut Name]]

that would seem to be in the spirit of these changes.

Thanks again for this—it’s shaping up really well. I’m looking forward to seeing this in action.

1 Like
7

I’d be interested in one for mail messages. I am not fully sure what’s possible, but I copy a lot of message:// URLs into drafts and this might help that.

8

Anyone interested in beta testing these features are welcome. Beta program details.

1 Like