[WIP] Linking and embedding

docs/0000-linking-and-embedding.md

@@ -0,0 +1,67 @@
+---
+Start Date: 2020-07-25
+RFC PR: (leave this empty)
+Foam Issue: (leave this empty)
+---
+
+# 0000 Linking And Embedding
+
+## Summary
+
+Linking and embedding defines a cohesive mechanism to use linking, embedding, tagging and aliasing in Foam workspaces.
+
+## Motivation
+
+Current Foam lacks several functionalities related to content linking and embedding:
+
+- Linking to anchors and titles is not well defined
+- There's no mechanism defined to embed content from one note to another
+- There's no mechanism defined how to place arbitrary anchors into a note
+- Notes don't support aliasing (i.e. alternative names)
+- Current wikilinks can be linked only by using a filename (without a path):
+  - No possibility to link using note titles
+  - No possibility to define explicit note sub-folder when using a filename-based linking
+- There's no well defined mechanism to use tagging
+- There's no mechanism defined to associate notes with tags
+- There's no mechanism to give an alternative titles for wikilinks
+- There's no mechanism to refer to other Foam workspaces with wikilinks
+- It's not defined how link reference definitions should work with all the items above
+
+To be able to do all these, a cohesive specification is needed that takes all the relevant aspects into account, offering good usability, while defining which functionalities are configurable and which ones are not.
+
+## Detailed design
+
+Due to length of the specification, it's separated into a separate document. Please see [[linking-and-embedding-specification]]
+
+Various considered syntax alternatives can be seen from [[linking-and-embedding-syntax-alternatives]].
+
+## Drawbacks
+
+Implementing all the mechanics into Foam will has several drawbacks:
+
+- While it gives users more power, it makes the solution also more complex to use.
+- In case Foam solely relies on external extensions and we want to get the best user experience, the following extensions should potentially be altered to some extent:
+  - Markdown Notes
+  - Markdown Links
+  - Markdown Preview (Enhanced)
+  - Markdown All in One
+  - (Markdownlint)
+- In case some of the functionalities are decided to be implemented into Foam itself, the potential extension functionality overlaps has to be analyzed.
+- Some of the current functionalities in Foam has to be refactored in all of the cases
+
+## Alternatives
+
+In case Foam is kept as a "curated extension platform", we could consider just integrating with some other similar extensions, like [Memo](https://github.com/svsool/vscode-memo) or [Dendron](https://www.dendron.so/) that already have some of the planned improvements implemented. The drawback is that these are currently "external" to Foam, so if Foam doesn't agree with some of their design philosophies, there's not necessarely much to do (besides forking).
+
+## Adoption strategy
+
+This shouldn't break any existing content; it just gives users new possibilities to work within their Foam workspaces (i.e. not a breaking change). However to get all these functionalities implemented and into use, see the extension change listing from [drawbacks chapter](#drawbacks).
+
+## Unresolved questions
+
+Exact implementation strategy still to be defined.
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[linking-and-embedding-specification]: specifications/linking-and-embedding-specification "Linking and Embedding Specification"
+[linking-and-embedding-syntax-alternatives]: linking-and-embedding-syntax-alternatives "Syntax Alternatives"
+[//end]: # "Autogenerated link references"