search

jgm / djot

A light markup language
https://djot.net
MIT License
1.67k stars 43 forks source link

Link between files and block #43

Closed wrvsrx closed 2 years ago

wrvsrx commented 2 years ago

Why

I saw you plan to add wiki link syntax (#26), then I was wondering if you plan to expand that wiki syntax to make it able to express accurate link to other djot files, even other djot blocks.

If we want to add a link to a.md, whose content is

# Head 1 {#anchor}

some content.

via regular markdown link, we have to write it as [link to a](a.html#anchor), which assume we want to convert the file to html. Wiki link is a better solution since it doesn't need to specify file extension name. But there are some cons of wiki link:

  1. It can't specify link to an anchor such as a.html#anchor
  2. It can be ambiguous. Djot doesn't require document title must be the same as its file name, therefore two documents can have same title.
  3. It only supports notes in the same level.

An example syntax

Following syntax is a rough proposal, just for expressing what function it can give. You probably need to polish these syntaxs before they come to spec.

  1. [[Tiger]]() means a link to Tiger.djot.
  2. [[Tiger]](../a.djot) means a link to ../a.djot with text Tiger.
  3. [[Tiger]](a.djot#anchor) means a link to an anchor point named anchor in a.djot.

When being converted to html, link to a.djot should be replaced by a.html.

Pros and Cons

If djot have a spec about links between file (even with blocks and inline elements), there will be some pros:

  1. We can have a unified rule to jump between djot notes/documents in editors (vscode, vim/neovim) or other note taking software (although currently there isn't such software based on djot).
  2. It will be easy to keep documents link relationship when publishing djot files as a website or other thing.
  3. Compared to markdown, a spec about link relationship between files avoids division about link syntax in different implementation. Link syntax extensions of markdown in different softwares such as Obsidian, emanote, neuron, zk, zettlr are not consistent.

Possible cons of that syntax is:

  1. It might need conversion software has awareness about file location when processing djot files with link, which may cause some inconvenience. For example, pandoc just knows the Text of inputs instead of (FilePath, Text).
wrvsrx commented 2 years ago

It seems that wiki link with anchor support can just do that. Example syntax can be changed to

  1. [[Tiger]] means a link to Tiger.djot.
  2. [[../a|Tiger]] means a link to ../a.djot with text Tiger.
  3. [[a#anchor|Tiger]] means a link to an anchor point named anchor in a.djot.
wrvsrx commented 2 years ago

Close it since wiki link (#26) should be able to do that.