RFC: Materialized links #4
Conversation
|
|
||
| ### Backlinks | ||
|
|
||
| You can already view backlinks inside the Markdown Notes backlinks explorer. Materializing backlinks adds the following benefits: |
There was a problem hiding this comment.
There was a problem hiding this comment.
Great writeup @jevakallio !
Overall, I think this will be a nice improvement to Foam. I only had one concern (see comment).
| The extension will replace the entire immediate content of the section following the H2-heading, either until: | ||
|
|
||
| - Next scope (next H2 or H1 heading) |
There was a problem hiding this comment.
When we go to implement this, I think we should be careful here. I don't know how I feel about it replacing everything until it hits the next scope. Rather than relying on something user-created (like the next H2 or H1), I would almost rather rely on something from Foam.
What if instead we put the list inside it's own fence using HTML comments similar to how [github-markdown-toc](https://github.com/ekalinin/github-markdown-toc) does it like so:
Table of contents
=================
<!--ts-->
* [gh-md-toc](#gh-md-toc)
* [Table of contents](#table-of-contents)
* [Installation](#installation)
* [Usage](#usage)
* [STDIN](#stdin)
* [Local files](#local-files)
* [Remote files](#remote-files)
* [Multiple files](#multiple-files)
* [Combo](#combo)
* [Auto insert and update TOC](#auto-insert-and-update-toc)
* [GitHub token](#github-token)
* [Tests](#tests)
* [Dependency](#dependency)
<!--te-->Notice the ts comment for table start and te for table end.
There was a problem hiding this comment.
is it that easy to have a comment in md?! 🤯
I am actually happy with either the section or comment approach, once we go for one we can use that approach across our generated code (e.g. also for link definitions)
There was a problem hiding this comment.
Right!?
I am actually happy with either the section or comment approach, once we go for one we can use that approach across our generated code (e.g. also for link definitions)
Agreed! Consistency is 🔑
|
|
||
| Links are formatted as traditional Markdown links `[Title](target.md)` | ||
|
|
||
| - This prevents a materialized backlink being treated as a regular link, which would cause every linking relationship automatically becoming two-way |
There was a problem hiding this comment.
not sure I understand, does this means that it's not allowed for someone to use the [Title](path/to/doc.md) syntax for local files?
| The extension will replace the entire immediate content of the section following the H2-heading, either until: | ||
|
|
||
| - Next scope (next H2 or H1 heading) |
There was a problem hiding this comment.
is it that easy to have a comment in md?! 🤯
I am actually happy with either the section or comment approach, once we go for one we can use that approach across our generated code (e.g. also for link definitions)
|
|
||
| - Mucking about user files can be fickle | ||
| - Non-trivial effort to implement and test the feature. | ||
| - (Current implementation): Using headings as link section delimiters can lead to destructivev updates, if user writes any content inside a Foam-managed section |
There was a problem hiding this comment.
| - (Current implementation): Using headings as link section delimiters can lead to destructivev updates, if user writes any content inside a Foam-managed section | |
| - (Current implementation): Using headings as link section delimiters can lead to destructive updates, if user writes any content inside a Foam-managed section |
Rendered RFC
https://github.com/foambubble/rfcs/blob/rfc/materialized-backlinks/docs/0000-materialized-links.md
TL;DR;
This RFC describes a solution to much requested features:
It also describes a nice-to-have feature, which we'll get (almost for free) as a by-product:
Feedback welcome! Discord user
@BSPrickhas indicated interest in implementing this feature, which is why I've written the RFC to guide implementation.