Wiki-links to headings in Markdown notes

DEVONthink
1

My understanding is that DEVONthink has support for wiki-links in the form: ‘[[DocumentNameOrAlias]]’, with associated support for automatically creating new documents when clicking on <DocumentNameOrAlias> when in Markdown edit mode.

Additionally, DEVONthink supports the (more verbose) Markdown syntax for links: ‘[Text](DocumentName)’. While ‘<DocumentName>’ can include the file extension (e.g. “.md”), this is optional. However, there doesn’t seem to be support for document aliases when employing this syntax. This is not entirely surprising given that these are generic Markdown links to external documents, that can be used for all kinds of documents (including Web URLs), and they can also employ absolute or relative paths. However, it would be nice to have the alias concept supported in the Markdown links in DEVONthink.

1. Are there any plans for supporting aliases in Markdown links?

The standard Markdown links also support referring to bookmarks/anchors within documents, in the form: ‘[Text](DocumentName#Bookmark)’. DEVONthink appears to have support for this, as well (but, there’s a caveat – see below).

I’ve noticed that DEVONthink automatically creates bookmarks/anchors for headings by converting the heading text to lower case and discarding all whitespaces (for example, the automatically generated bookmark for “Heading or Title” is “headingortitle”). While this is consistent with Marked 2, other Markdown editors/processors replace spaces with dashes – which is also the approach taken by GitHub.

2. Would it be possible to provide an option in DEVONthink (e.g under Preferences → Files → Markdown) to allow users to choose the approach taken for generating heading IDs?

The MultiMarkdown syntax has provision for specifying a custom heading ID (i.e. bookmark), by adding the following immediately after the heading (on the same line): ‘{#custom-heading-id)’, where ‘<custom-heading-id>’ can be any text that complies with the corresponding HTML requirements. Many Markdown editors have support for custom heading IDs, as does Marked 2. Unfortunately, the Markdown editor in DEVONthink does not seem to have support for custom heading IDs.

3. Are there any plans for supporting custom heading IDs?

While we can use the automatically created bookmarks for headings in Markdown links in DEVONthink, they do not appear to work in wiki-links – i.e. this doesn’t work: ‘[[DocumentNameOrAlias#Bookmark]]’. This syntax is supported in a wide range of Markdown editors that have wiki support.

I should add that, just like Markdown links can refer to bookmarks located in the current document without having to specify the document name (i.e. ‘[Text](#Bookmark)’), other Markdown editors that have wiki support employ the following syntax for wiki-links to bookmarks/headings in the current document: ‘[[#Bookmark]]’.

4. Are there any plans to extend the wiki-links syntax to provide support for bookmarks?

Perhaps I should have split this in two separate posts – one for wiki-links and one for custom heading IDs. However, the topics are very closely related and I would be thrilled to see these enhancements implemented in DEVONthink in the near future.

2

Where do you see that in the MMD documentation?

In the meantime, a simple javascript could take care of that.

3

Custom heading IDs are actually supported, DEVONthink uses the MultiMarkdown syntax:

# Heading [MyID]
1 Like
4

I may have spoked out of line regarding the custom heading IDs syntax being present in the MultiMarkdown specs. I thought I learned about it from Fletcher Penney’s MultiMarkdown website but, in fact, I think I may have gotten it from Matt Cone’s Markdown Guide. Alternatively, I may have come across it in the Pandoc documentation. Anyway, the syntax is supported in the Markdown editors and tools I’ve been using for many years – including Marked 2. So, I kinda took it for granted…

Can you provide more details on how I could use JavaScript to change the way heading IDs are generated by DEVONthink?

5

Having just tested it, I can confirm that it works. I wasn’t even aware that this syntax was introduced in MultiMarkdown 5. While I can see why the DEVONthink team decided to embrace it, I’m not aware of any other Markdown editor that uses it. For what it’s worth, Obsidian is using the following (which I’m not all that keen on, either):

# Heading ^MyID

Would it be possible to have an option in DEVONthink (e.g under Preferences → Files → Markdown) for the syntax employed for custom heading IDs?

The square brackets syntax can be the default (for backwards compatibility), but also offer the curly braces syntax as an option. It would be nice to also have an option for the Obsidian syntax, but it would be understandable if you were reluctant to go as far as that.

6

The joys of Markdown - each app has its own flavor :pensive: Personally I think that the MultiMarkdown syntax is a logical extension of the Markdown syntax. A future release might offer additional options but no promises.

6 Likes
7

Yes. Standards are a beautiful thing. Except, they are seldom available from the onset. Instead, they tend to “emerge” based on what has proven to stick (out of many competing attempts).

Any thoughts on wiki-links for headings? (which was the main question in the original post)

8

In general, you’d use something like

document.addEventListener('DOMContentLoaded', () => {
  // do your stuff here 
})

and provide that as JavaScript to be loaded for every MD file in your global preferences. Caveat: Put that somehwere in your file system, i.e. outside of DT, so that it’s available to browsers, too.

Now, in the case of the header ids, its getting a tag more complicated than I though. A simplistic approach might be this (inside of the event listener callback replacing the “do your stuff here” comment)

  const headers = document.querySelectorAll('h1, h2, h3, h4, h5, h6');
  headers.forEach(h => {
    const text = h.innerHTML;
    h.id = text.toLower().replaceAll(" ", "-");
  })

That will set the id for “Heading or Title” to “heading-or-title” and it might work well for you own MD. If you stumble on MD generated by, for example, snipping a web site into DT, the heading might contain additional stuff (e.g. after a vertical bar). So, a more refined function might be needed in these cases, perhaps stopping at the first non-alphanumeric character or so.

And then there’s the question of special characters like ‘#’ or ‘&’ in the heading’s text. I guess, those will have to be URL-encoded.

But frankly: I think your request for a more configurable ID is a good idea. Simply lowercasing them and removing all spaces is not wrong, but the IDs are a bit awkward, in my opinion.

9

See above (“A future release might offer additional options but no promises.”)

10

These facilities/customisations (and many others) could be implemented by end-users if DEVONthink would offer custom pre-processing for Markdown notes similar to the corresponding feature in Marked 2.

11

I’m using version 3.9.6, and this syntax of custom id does not work. Could you please help?

Assume I have hello.md with its item link as x-devonthink-item://D33DF540. The content is

## Heading 1
... very long content
## Heading 2 [customID]

In another md file, I try to refer to the custom anchor link. When I click into the link, DevonThink doesn’t take me to Heading 2.

[Link](x-devonthink-item://D33DF540#customID]
12

Welcome @tmhung
DEVONthink has its own section link syntax for this purpose…

[New Markdown Text 1.md](x-devonthink-item://0F244186-EF9A-485C-BE5D-9695EDC04DD3?section=section2)
13

Just to clarify: You’re using an item link with a proprietary protocol (x-devonthink-item). The syntax with the #fragment works only for http/https and possibly file links. I you want to use item links, you must use the syntax @BLUEFROG described.

1 Like
14

Would you mind explaining what section2 is? Is it the order of the heading? If yes, I’d find such anchor link fragile. Any time, I add/remove/modify a heading, then some references of existing anchor links are broken.

Regardless, I tried your suggestion but didn’t work.

[New Markdown Text 1.md](x-devonthink-item://0F244186-EF9A-485C-BE5D-9695EDC04DD3?section=section2) // not work

[New Markdown Text 1.md](x-devonthink-item://0F244186-EF9A-485C-BE5D-9695EDC04DD3#heading-2) // work
15

The section link uses the name of the section, not the order.

image
image2044×1126 402 KB

PS:

1 Like
16

Thanks a lot. I confirm the syntax works x-devonthink-item://item-id?section=lowercase-section-name.

I have two more questions:

  • Is it possible to refer by a custom ID instead of a section name?
  • How can I check the version of MultiMarkdown used by DevonThink 3?
17
  • Is it possible to refer by a custom ID instead of a section name?

You can use a syntax e.g.,…

## Stats [e]
  • How can I check the version of MultiMarkdown used by DevonThink 3?

DEVONthink currently uses MultiMarkdown v6.6.

1 Like
18

Worked wonderfully.

## Stats [e]

@BLUEFROG It’s my first time on this forum. I love both the product and the fantastic support. You have a great day sir.

1 Like
19

Welcome to the forums and thanks for the kind words. They’re very appreciated! :slight_smile: