Multiple title and linking systems

[tchayen]

I am opening a common issue to discuss various systems for linking and discovering titles that I am aiming to support at some point in the extension.

I would love to have some discussion here first to find out what people expect and what are the chances that those expectations can live together.

Linking

As a reminder, there are only two ways to link files in Markdown: links and references. All the other methods like [[Linking by title]], linking by some arbitrary ID ([[20200715001]], <g04d0sa2>) are not part of the CommonMark standard and will be present in Markdown Links only as configurable options.

Possible options

• [[Wiki link]] maps to kebab case filename of the same string Support Markdown Notes style of wiki links #21 (Some kind of a title links to some-kind-of-a-title.md if such file exists).
• [[Wiki link]] maps to title (see Title discovery below).
• [[Wiki link|Alias]] (as the two above).
• Zettlr-style links (already supported by default, will be moved out to an option).
• Neuron-style links (<iD0f4f1l3>). Deprecated.
• [[[Folgezettel link]]] used in Neuron and described here.
• Foam-like references ([Reference]: file-name instead of [Reference]: file-name.md)

Title discovery

I have used an assumption that title of the file will be the first heading of rank 1, but of course it is not true for everyone.

What comes to my mind is settle on several ways to discover a title, give them some default precedence and make it configurable.

An example default can be:

1. Frontmatter title
2. Rank 1 header if there is only one
3. Filename if globally unique
4. Filename with the enclosing directory

What's next?

Please comment the issue with your idea about linking if you have one. Please share your feedback about the the things I have mentioned above. As soon as we find a way to support all alternatives (or come to conclusion that it is out of scope) we can start implementing support for those.

[kevinslin]

Like the general design of having a precedent list with common markdown title conventions and a config for updating the list.

as an escape valve for esoteric conventions, maybe expose a “regex” rule to let people create their own conventions?

[fmagin]

Are Link Reference Definitions currently supported? They don't seem to be working in the version which gets installed in VS Code, at least they don't show up in the rendered graph. The initial issue description is currently ambiguous and just states that it is part of the CommonMark standard and not whether that standard is fully supported.

[tchayen]

Right, I didn't make it clear which ones of those are supported now. Although references should work 😞 . I will make sure to check it once I will be fixing bugs.

[fmagin]

Found the issue. Foam currently generates the references as:

[Type Theory]: type-theory

and not as

[Type Theory]: type-theory.md

The former is required to support Github pages. A quick check indicates that Markdown Links supports the latter, but not the former. It can be argued that this isn't exactly conforming to the standard, still might be interesting to support though.

[tchayen]

@fmagin Thanks!

Added it to the list of desired options.

[raffomania]

I use markdown files without headings and would love for them to show up in the graph :) I would be perfectly happy if there was a fallback to file paths (with directories) in case there is no heading present.

[tchayen]

@raffomania thanks so much for the feedback! I can't promise anything anytime soon, but the idea described in the first post should cover your case once it's done.

[srid]

Neuron is moving away from <..> style links -- so it is alright if you don't support them -- however folgezettel links ([[[..]]]) will be used very commonly, so it would be nice if markdown-links supported it. I suppose you can simply ignore the outter brackets when parsing for [[..]] to achieve this.

[srid]

1. Frontmatter title
2. Rank 1 header if there is only one
3. Filename if globally unique

FWIW, neuron went with the exact priority sequence to determine note title. (Filenames are always globally unique; so there is no step 4 in neuron).

(3) in particular is interesting to me, because then I can rename the file without also having to change the title.

[tchayen]

Neuron is moving away from <..> style links -- so it is alright if you don't support them -- however folgezettel links ([[[..]]]) will be used very commonly, so it would be nice if markdown-links supported it. I suppose you can simply ignore the outter brackets when parsing for [[..]] to achieve this.

Ok then, I will remove that from the list.

Regarding parsing – does anyone from the Foam team know how you guys handle those section links?

[jaiamo]

Seconding request (in closed issue above) for piped wikilinks support (ie [[link|alias]] format also used in vscode-memo)

[srid]

[[[Folgezettel link]]] used in Neuron and described here.

btw, the link for that has been moved here: https://neuron.zettel.page/linking

[srid]

Note: neuron is switching from [[[..]]] to [[..]]# (or #[[..]]) for folgezettel: srid/neuron#514