Long-term Link and Storage Strategy

[perber]

Problem

LeafWiki stores pages as Markdown files on disk, but serves them as a web application. This creates a semantic gap between Markdown links, filesystem paths, assets, page slugs, and web URLs.

Currently, links are primarily stored as they are visible/usable in the LeafWiki UI. This keeps the web model simple, but it may create friction for external tools that expect file-based Markdown links such as ./page.md, /folder/page.md links.

We need to define LeafWiki's long-term link storage and rendering strategy.

It should not break the existing model and files should still work in future releases.

[mry]

Attachments and structural variants are also an issue for other markdown tools today.

Cross platform would quickly be an issue as well, or rather a windows specific issue.

[perber]

Good point. So the strategy should probably explicitly cover attachments, page structural variants like page.md vs page/index.md, and cross-platform path normalization, especially Windows path separators and filename constraints. I’ll expand the issue scope beyond page links only.

[mry]

I was specifically thinking about path length issues on Windows.

https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=registry

[perber]

@mry Thanks for pointing that out!

Yeah, this seems to be a hard issue on Windows when long paths are not enabled. It could potentially affect LeafWiki’s tree-based storage model, especially around deep hierarchies.

It needs more investigation and a clearer decision about which trade-offs are acceptable.