Project: enable latest versions in embeds

Problem

Permanent links are important to make the content inside the network to be accessible all the time. But in some cases referring to a mutable reference is relevant, specially when we are talking about publishing content to a group/site.

At the moment, our method of storing references in permanent data lacks the ability to specify the "latest" version. Instead, the reference will include the specific version it points to or the most recent version available in the node at the time the reference is created.

Solution

The solution include two parts: The editing part and the visual part.

Creating embeds

Before we get into editing an embed, we need to understand what are the ways create embeds in the draft: By using the Sidemenu and by pasting a reference and selecting the "Embed" option from the context menu dropdown.

When adding references to other content, it's crucial to maintain the author's intent. This entails preserving the exact text the author included in their draft, regardless of how the reference is resolved. While this may not have significant impact currently, it is expected to become important soon. In both ways we are creating embeds we need to store the user's intent.

This means that we need to store more information in the permanent data when this actions happen. We will cover the new data we need to store while we cover all the scenarios.

After the author creates the embed block type, we should introduce a new UI allowing them to choose between the exact version at the time of addition or the latest version, effectively achieved by omitting the version parameter from the reference.

// reference to the exact version
hm://d/otorBG9gLJZMi4D2fB9NtZ?v=bafy2bzaceaz5lsnvfgrwqzhtdu4xmb4uhfeihp5hzyzc62jzyrce6akalaxmq.bafy2bzacebctassmwajzfcedl5kyqpraoyfnejsyahpqh7zq7oqsdkzkm4i6q

// reference to the latest version in the current node
hm://d/otorBG9gLJZMi4D2fB9NtZ

To enable this, we need to store this data as attributes in the permanent data: sourceURL, sourceRef and showLatest (The attribute names of the attributes can change)

sourceURL is the exact text the author added to create the embed. we need to store this because this could be a site link and we want to store the original intent of the user as said before.

sourceRef is the resolved reference that the sourceURL is currently pointing to. This is specially needed when the sourceURL is a site URL because currently we do the reference resolve entirely in the frontend.

showLatest is a boolean value that determines which is the version to show when rendered.

This is the result JSON value that will be stored in the permanent data:

{
  type: 'embed',
  id: '12345',
  ref: 'hm://d/otorBG9gLJZMi4D2fB9NtZ?v=bafy2bzaceaz5lsnvfgrwqzhtdu4xmb4uhfeihp5hzyzc62jzyrce6akalaxmq.bafy2bzacebctassmwajzfcedl5kyqpraoyfnejsyahpqh7zq7oqsdkzkm4i6q',
  text: '',
  attributes: {
    view: 'card',
    showLatest: 'false',
    sourceUrl: 'https://myexamplesite.com/example-document-path',
    sourceRef:
      'hm://d/otorBG9gLJZMi4D2fB9NtZ?v=bafy2bzaceaz5lsnvfgrwqzhtdu4xmb4uhfeihp5hzyzc62jzyrce6akalaxmq.bafy2bzacebctassmwajzfcedl5kyqpraoyfnejsyahpqh7zq7oqsdkzkm4i6q',
    childrenType: 'div',
  },
}

Avoid Redundant information

As you can see in the example JSON above, there's a high change that the values in sourceRef and ref can have redundant data (documentID). We can avoid this problem by Storing sourceVersion instead of sourceRef .

{
  type: 'embed',
  id: '12345',
  ref: 'hm://d/otorBG9gLJZMi4D2fB9NtZ?v=bafy2bzaceaz5lsnvfgrwqzhtdu4xmb4uhfeihp5hzyzc62jzyrce6akalaxmq.bafy2bzacebctassmwajzfcedl5kyqpraoyfnejsyahpqh7zq7oqsdkzkm4i6q',
  text: '',
  attributes: {
    view: 'card',
    showLatest: 'false',
    sourceUrl: 'https://myexamplesite.com/example-document-path',
    sourceVersion: 'bafy2bzaceaz5lsnvfgrwqzhtdu4xmb4uhfeihp5hzyzc62jzyrce6akalaxm',
    childrenType: 'div',
  },
}

Removing the version parameter from the ref attribute is important because this is the way we make sure the backend consider all the changes of a document as reference materials when pushing content to sites/gateways.

Warn authors when selecting the latest version of possible issues

Due to the system's design, displaying the latest version of a reference may yield unexpected results. It's crucial to alert the author and, when possible, avoid referencing the most recent version if it's beyond the author's control. We can also add a setting to the application to ignore this warning on future attempts.

Reading Embeds

When we render the document, we should be transparent and show the reader what we are actually rendering.

Rendering the exact version or a reference

In this case, we should do the same as we are doing now, because what the author wanted to show is what the reader is going to get.

Rendering the latest version of a reference

When the attribute showLatest is true, we will render the latest version the current client have available for the defined reference. While this was the author's intent, we believe we need to be explicit with the reader by exposing the fact that what is being displayed is the latest version.

In this context, the sourceVersion attribute is significant as it allows us to determine whether there is a discrepancy between the current version and the one referenced by the author at the time of publication. If these values differ, we can display a visual cue, such as a banner, to indicate that the version being viewed is more recent than the original.