Allow inclusion of note when using reference definitions

[pderaaij]

Fixes #794.

The idea is that when we want to include a note that is also referred in the link definition, we can just "remove" that definition. This prevents the tokenisation to distort the inclusion format.

[riccardoferretti]

stupid question: why don't we just remove all (generated) reference definitions from the preview? do they serve a purpose?

[pderaaij]

That would lead to the problem for the explicitly defined link references. At this level in the MarkdownIt parser, we can't differentiate between implicit and explicitly generated definitions.

[riccardoferretti]

IIUC:

• the goal of including link definitions is so that in preview links can be followed
  • we don't need that for our links (which are source of generated definitions) because we resolve the address in the link itself
  • but the user could have extra definitions, which are needed to resolve the link
• given that in the preview external (non generated) link definitions are useful, we cannot just remove all link definitions
• it would be ok to remove all our generated link definitions, but because we can't tell them apart from the external ones, we can't simply do that - instead we can remove the ones that cause us trouble (which we always assume to be internal?):
  • wikilinks with aliases
  • "wikilinks" for included notes

Does it even make sense to have a definition for an embedded note? there is no link to follow there
Maybe the solution here is to not create definitions for included notes?

[pderaaij]

* the goal of including link definitions is so that in preview links can be followed

In the context of retaining the definitions for preview, this is correct. In the broader sense, the definitions are there for publication.

  * we don't need that for our links (which are source of generated definitions) because we resolve the address in the link itself
  * but the user could have extra definitions, which are needed to resolve the link

* given that in the preview external (non generated) link definitions are useful, we cannot just remove all link definitions

* it would be ok to remove all our generated link definitions, but because we can't tell them apart from the external ones, we can't simply do that - instead we can remove the ones that cause us trouble (which we always assume to be internal?):
  
  * wikilinks with aliases
  * "wikilinks" for included notes

All above, correct.

Does it even make sense to have a definition for an embedded note? there is no link to follow there Maybe the solution here is to not create definitions for included notes?

We could create some magic to leave it out there. But, that makes life harder for publishing. Not sure what the best UX is here. I could imagine that even embedding does not work when publishing, I at least can manually follow the link because the definition is there.

[riccardoferretti]

We could create some magic to leave it out there. But, that makes life harder for publishing. Not sure what the best UX is here. I could imagine that even embedding does not work when publishing, I at least can manually follow the link because the definition is there.

Yeah I think we are aligned.
I agree that embedding is outside of our control (it's the publishing fwk's job), but it's fair to keep the link as a sensible fallback.

Ok, let's go forward with your original proposal, will comment in code

[riccardoferretti]

The approach sounds good to me, I think it would be good to provide better in-code documentation so that our future selves can understand why we went this route

[riccardoferretti]

Looks great, thx!