djot
djot copied to clipboard
jgm
Wikilinks
It would be good to support wikilinks, in the style of obsidian:
[[Page Name|optional description]]
Whenever I have a pile of files (directory of directories of files, possibly a few levels deep), and I want to link to one doc from another, I've always just written my links like [whatev](../path/to/whatev.html). That is, I'm familiar with where the other doc is relative to the current doc, so it's no trouble to explicitly write out the link like usual. I'm probably missing something here --- what is the rationale for having a wikilinks-style linking syntax?
It's not really necessary, but in heavily-interlinked systems of documents, like notes, it is more convenient to write see [[Tigers]] than see [Tigers](tigers.html).
Ah. I see. For wiki's:
- all docs/pages are at the same level, and
- doc names / page names often have spaces in them,
so that shortcut syntax is convenient. For my "nested piles of notes", I don't often want to write
-
[path/to/foo-bar-tomatoes](path/to/foo-bar-tomatoes.html)anyway, but rather -
[how to grow tomatoes](path/to/foo-bar-tomatoes.html).
Also though, since djot doesn't use double characters for markup (e.g., there's no **bold**), I don't think [[foo]] would be consistent with djot's syntax. And djot doesn't use any left-right matching double-char syntax anywhere, I don't think.
I see that gitit uses [foo]() as a shortcut for [foo](foo.html). This might be useful if you're writing a wiki using djot.
I agree that [[page]] seems inconsistent with djot principles and that [page]() or something like [description](:page)could be used. However different wikis will normalize whitespace/punctuation/case differently, so that would have to be addressed somehow; perhaps a callback which receives the stringified link text?
I think the worry was not about double delimiters per se, but about ambiguities arising from their interaction with single delimiters. I don't think this case poses a serious problem, especially because we have directional delimiters here [ vs ].
@jgm , in your example
[[Page Name|optional description]]
What purpose does "optional description" serve? That is, if [[Page Name|optional description]] were rendered at html, how does "optional description" show up? Is it a tooltip if you hover on that link? (Hm, I seem to often mix up the "alt" and "title" attributes here.)
Incidentally, whenever a syntax has two things in a row like that, I always find it difficult to remember what the order is. I think it's more readable to have [[Page Name]]{alt="alt desc" title="the title"} if that's what's desired (erg... would that mean [[Page Name]] is short for [Page Name](Page%20Name.html)?).
It's the link text. And yes: the order is an issue; in fact, different wiki engines treat the order differently.
Would you consider supporting path and anchor in wiki link. For example
-
[[Tiger]]means a link toTiger.djot. -
[[folder/a|Tiger]]means a link tofolder/a.djotwith descriptionTiger. -
[[a#anchor|Tiger]]means a link to an anchor point namedanchorina.djot.
Maybe there should be a clear spec about whether we should use either path or path without extension in wiki link. If djot file has a specified extension (such as .djot), I think using path without extension will be more concise.
@wrvsrx , the idea is that [[foo]] would potentially render to link to foo.html, not to foo.djot (since the human reader would presumably want to see the rendered html page). In the less common case of wanting to link to foo.djot, you'd have to write out [foo](foo.djot).
Anyhow, sorry about the confusion above re double-delimiters vs double matching (left-right) delimiters. I missed that distinction when I wrote my comment.
Personally, I've never found the need for a [[foo]] syntax. For one thing, my file names often contain hyphens, but I don't want the link text to have the hyphen, e.g.:
[chocolate vs. vanilla](chocolate-vs-vanilla.html)
And another reason I haven't felt the need for them: most of the time I'm wanting to give a more descriptive link, as in [yes, I'm not kidding, cashew cheese nachos](cashew-nachos.html).
But, like I mentioned earlier, I can see it being useful specifically for implementing a wiki.
Given the many uncertainties surrounding wikilinks, not least of which is what goes before and after the pipe[^1] perhaps some convention for interpreting a regular link would be better. Assuming there is metadata (#35) one could have
+++
: baseurl
/wiki/
: default-extension
.html
+++
The article about [Tigers](*).
The article about [striped cats](Tigers*).
[What tigers eat](Tigers*#food)
Where by convention a lone * as the URL means "take the link text, possibly apply some transformation to it, append the default extension and prepend the baseurl and use that as URL" and an URL containinh an * means "replace the * with the default extension, and if the URL is relative prepend the baseurl".
That way the whole thing could potentially be handled by the host program and/or a filter. I have a filter for Pandoc which does this (and more).
[^1]: Personally I'm in favor of having the text before the pipe because that is the part which is always included.
@wrvsrx , the idea is that
[[foo]]would potentially render to link to foo.html, not to foo.djot (since the human reader would presumably want to see the rendered html page). In the less common case of wanting to link to foo.djot, you'd have to write out[foo](foo.djot).Anyhow, sorry about the confusion above re double-delimiters vs double matching (left-right) delimiters. I missed that distinction when I wrote my comment.
Personally, I've never found the need for a
[[foo]]syntax. For one thing, my file names often contain hyphens, but I don't want the link text to have the hyphen, e.g.:[chocolate vs. vanilla](chocolate-vs-vanilla.html)And another reason I haven't felt the need for them: most of the time I'm wanting to give a more descriptive link, as in
[yes, I'm not kidding, cashew cheese nachos](cashew-nachos.html).But, like I mentioned earlier, I can see it being useful specifically for implementing a wiki.
@uvtc When I say "a link to Tiger.djot", I mean a link in souce code level, so that a editor can know there's a link and we can jump between them. When converting to other format or rendering, the extension being added should be changed accordingly.
By the way, I just think we need a unambiguous standard to represent the link between source file, no matter using the wiki format or the format suggested by @bpj .
@bpj's suggestion about conventions is a good one (and similar to what I did with gitit, where wikilinks were [Like This]()).
This would not require a change to the syntax; processors could simply implement this convention.
Another advantage of [foo]() is consistency with the way label-less reference links already work in Djot — i.e., [foo][] is equivalent to [foo][foo].
