RFC 47 - Better Note References

[rlh1994]

This is the discussion for RFC 47 Better note refrences

The key points are to enhance the note reference (![[...]]) capability to include start/end of note places and change the default behaviour to reference to the next header or equal or greater level.

[jonathanyeung]

Thanks a lot @rlh1994 for helping write up the RFC. Overall, I like it, just a few minor comments (some of these are maybe more directed towards @kevinslin)

• Can you give me an example of when you'd want to reference the frontmatter of a different note?
• More of an implementation detail, but rather than calling the setting enableSmartHeaderReferences, I think it'd be better to have it be the opposite form, i.e. useLegacyReferenceSyntax. Also, I think we can be more aggressive with the migration in setting the new syntax as the default. The data we see indicates that overall usage of note refs today is very low, so I'd rather have new users discovering the feature be on the new syntax to start with.

[kevinslin]

Can you give me an example of when you'd want to reference the frontmatter of a different note?

in a lot of templates today, we start of with

## Summary

{fm.desc}}

the reason we do this is to note reference the description in another note. we really just want to note reference the description by itself. it also helps with more granular references (when you don't want to reference the whole note but for example, embed the uri or something other property of a note

useLegacyReferenceSyntax

sounds good to me

[hikchoi]

super nitpick 😅 on the fact that we should call it enableLegacyReferenceSyntax as per convention:

Be conservative and consistent about the choice of verb in the configuration names that are in the transitive verb form.

[hikchoi]

On frontmatter references

As described in the tradeoffs, I agree there is some overlap with the advanced queries. especially for frontmatter.
I would also imagine frontmatter references has to be rendered in-line in most cases. At this point, an in-line render of a note reference seems like a very roundabout way of frontmatter variable substitution.

I think it boils down to what we consider a "transclusion".
Personally I would scope transclutions to note level and section (block) level, but not frontmatter.
I would rather see frontmatter variable substitution be enhanced so that it can reference a note other than itself, and use that reference to resolve what should be rendered.

The work that needs to be done would be similar, or even less because we don't have to worry about the intricacy of how a frontmatter reference is going to be rendered if it is a note reference.

Maybe we can implement note frontmatter reference so that the note reference grabs an object that holds all frontmatter as properties, and we can pass that object into the variable substitution syntax

foo.md:

---
id: foo
desc: "this is foo"
status: "pending"
priority: "high"
...
---

bar.md:

---
id: bar
imports:
  foo: ![[foo#>]]
...
---

## Notes

<!-- example of an inline note frontmatter reference feeding into frontmatter substitution -->
The current status of [[Foo task|foo]] is {{ ![[foo#>]].status }}

<!-- example of grabbing the frontmatter reference from the note's frontmatter itself -->
The priority of [[Foo task|foo]] is {{ fm.imports.foo.priority }}

Maybe this is already going into the "advanced logic" territory of what we are planning to do with Queries, but I what I'm trying to say is that including frontmatter in what note references can retrieve seems slightly off-scope given

• the nature of what a frontmatter is (it's metadata, resolves to a single value),
• the need to render frontmatter that always resolves in a single value in the same way that we are rendering transcluded blocks of note content.
• and what note references are used for (to transclude block(s) of a note's content in other notes).

[hikchoi]

After noodling on this thought a bit more, I relax my stance on this matter.

There's no denying a capability to reference other note's frontmatter is going to come in handy. If we can have this capability without spending extra time spec-ing out how it should work in an ideal world, I would say it's worth it for the time being even if it feels a bit out of place.

However I still think that this shouldn't remain the only way we can reference other note's frontmatter. We should definitely iterate on how this could be done better in other avenues and promote doing it that way.

[rlh1994]

I think you're right; it's hard to think of a case where you wouldn't want to frontmatter to be rendered in-line.

For me I guess it's an AND thing, if it isn't much extra effort to add it then why not throw it in with this but it still renders in the same way as other references, but I agree that there's probably a separate enhancement to enable the {fm.desc} to be able to reference other notes as well, probably via a different syntax as reusing the ![[ feels clunky and inconsistent in terms of output.

[hikchoi]

Yeah, we can give special treatment to the note frontmatter references so that they are rendered differently. It's just that with variable substitution already doing exactly what frontmatter reference rendering should look like, it feels a bit off trying to force it conceptually as part of note reference.

Though my stance is that after weighing the value of being able to reference frontmatters vs. very very roughly projecting how much extra work it will require, I do think it is worth implementing.

[SeriousBug]

Great writeup, and I'm highly in favor of making references only include up to the next heading by default.

The front of the note syntax #^ clashes with the syntax for block anchors #^anchor. It might be confusing, and it might make development more difficult. Are there any alternative syntaxes we can use instead?

[rlh1994]

I did mention that, from a user point of view I could understand it as "it's an empty block anchor, which is the top of the note", ideally the end of the note could have been \/ if a symbol existed.

But if it makes dev more difficult then no need to go with it. maybe #~ ?

[kevinslin]

The reason for ^ is to stick with regex syntax of beginning of note. I don't think it will clash with block anchors in the sense that an empty block anchor shouldn't be valid