2025-05-05

2025-05-05

Norgolith

Continue implementing .ul-docs macro.

Some interesting problems I found on link system design:

What should we do with {/posts/foo}? I mean, <a href="/posts/foo"> is a valid anchor.

Ideas:

  • We can force user to use file:/// to explicitly state for absolute path from filesystem

  • We can implement dedicated apis to create relative/absolute(from workspace) links:

    • (neorg/create-relative-target origin path)

    • (neorg/create-absolute-target path)

    Both origin and path should be absolute path from filesystem

    But what should these apis return?

Link Sytnax design

  • linkables starting with { : local link

    A local link can be resolved in single-file mode because it will always pointing somewhere in same document like * heading or using raw url like /posts/foo or https://example.com

    A local link can be exported without need of Neorg-like application

  • linkables starting with {: : app link

    An app link can only be resolved when a workspace is defined. It can point to somewhere else in current workspace or even from external workspaces e.g. :foo, :/about or :$foo:path

    An app link can only be exported from Neorg-like application

  • :/path points to path.norg or path/index.norg in current workspace root.

  • :$foo:path is same to :$foo:/path


{ : $foo : path/to/file : * heading }
  ^ ^^^^ ^ ^^^^^^^^^^^^ ^ ^^^^^^^^^
  | |    | file path    | local scope
  | |    |              |
  | |    |--------------'
  | |    |
  | |    scope delimiter
  | |
  | workspace name
  |
  app link prefix

So now I fixed my mind with user-perspective, but how can I make link system modular?

Like, I can convert absolute path to correct target and vice versa, but how can I convert rich target to actual link in different markup language / export targets? Is JanetString a type capable of handling every export targets?