markdown-links icon indicating copy to clipboard operation
markdown-links copied to clipboard

Published 20 hours ago • verified publisher icon tchayen

Multiple title and linking systems

Open tchayen opened this issue 4 years ago • 13 comments

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 #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.

tchayen avatar Jul 15 '20 09:07 tchayen

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?

kevinslin avatar Jul 15 '20 23:07 kevinslin

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.

fmagin avatar Jul 21 '20 08:07 fmagin

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.

tchayen avatar Jul 21 '20 12:07 tchayen

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.

fmagin avatar Jul 21 '20 14:07 fmagin

@fmagin Thanks!

Added it to the list of desired options.

tchayen avatar Jul 21 '20 19:07 tchayen

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.

raffomania avatar Sep 09 '20 11:09 raffomania

@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.

tchayen avatar Sep 13 '20 15:09 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.

srid avatar Sep 13 '20 16:09 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.

srid avatar Sep 18 '20 20:09 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.

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?

tchayen avatar Sep 20 '20 20:09 tchayen

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

jaiamo avatar Nov 24 '20 15:11 jaiamo

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

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

srid avatar Dec 23 '20 20:12 srid

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

srid avatar Jan 22 '21 18:01 srid