Discussion to standardize page and block terms

General
1

@tienson recently informed me that pages are soon going to get alphanumeric IDs just like blocks have. This will affect the ideas below, but let me put my current thinking out there so others closer to the code can help sort through these complicated issues.

We need to figure out the right way to talk about links and embedding. The current language is confusing. This will be important in figuring out how to describe current behavior, request new features, and fix bugs. Bear with me in the below text because I will be using terms that are currently being used in multiple ways, so when I say “link” I may mean something different than you have in your mind. But do correct any conceptual mistakes I make.

There are three types of connections between plaintext references in a block and target content outside of that block. A link connects a plaintext reference in one block to target content outside that block in some way. The link has two parts: a display (what shows in the rendered block) and a reference (the target of the link). The reference has both a unique ID (UUID) and what I’ll call "target content’, or just “content” for short, which is just whatever is in the page or block that is named by the UUID.

The link can currently be shown in three ways in a rendered block:

  1. what is displayed: text formatted as a link; reference content is shown only when the link is clicked and the user is taken to the content - this currently includes both Markdown links (page, block, and web) and page links
  2. what is displayed: reference content from another location, formatted to indicate that the content is being transcluded from the another location - this currently includes what we are currently calling “block references”, which already has a different meaning in the glossary—there, a block reference = a block UUID, not a UUID inside (( ))—but this type of transclusion can’t currently be done for Logseq pages; I don’t know if it can be done for files or web pages but people will want it for images at least
  3. what is displayed: what I’ll call an “embed frame” that has a distinct background color; reference content is shown inside the embed frame - this is what we are calling an embed (block, page, or YouTube)

So there are three combinations of display/content, but we don’t have 3 distinct ways of talking about them, and we also currently have some inconsistencies:

  • what we are calling page titles = page IDs, but what we are calling block titles = text beginning block content up until the first line break
  • page links put page IDs in ( ) without the page ref syntax of [[ ]], block links put block IDs in ( ) with the block ref syntax of (( ))
  • block IDs inside (( )) display block content, but pages inside [[ ]] display the page title as text that links to the page

One idea that will require editing the current glossary and usage is to refer to page titles and block UUIDs as IDs, internal links to pages and blocks as “references”/refs, and Markdown links to Logseq pages, blocks, external web pages, and files as “links”. This would mean:

page IDs = page titles, block IDs = block UUID codes
page refs = [[page ID]], block refs = ((block ID))
- page refs (change from current term “page links”) display styled page IDs, clicking navigates the user to the page target
- block refs (continue current use of term) display styled content of the block target
page links = [link text](page ID), block links = [link text](((block ID))), file links = [link text]([[file://path/file.md]]), web links = [link text]([[https://url.html]])

Obviously, adding alphanumeric page IDs would mean that page titles could not be page IDs, so we would have to rethink this. Comments welcome!

1 Like
2

my 2 cents, wherever that’s possible, we should label concepts according to what the user sees or reads while using the software.
For instance, the page title :

page-title

  • I would prefer page-title over page-ID or anything else because :
    • in the front matter, the title: is a specific attribute of a page, so page-title makes more sense than page-ID (as the word ID is never mentionned in the UI)
    • an ID is usually used to identify an entity in a database or an array, so the term might be confusing in this context (as the browser version of logseq uses the indexdDB)

page-reference

  • page-reference = [[page title]]
  • in other words: a page-reference is a link to a page , using its page-title as the reference object
  • I think page-reference is more specific than page link : as you noted a link can be anything from a web url, an internal link to a page (a page-reference), a link to a document on the local system, etc… link is just too broad.
    page links can be understood as link to a page, but could also mean links inside a page (links from a page)

block-references

  • a block-reference = ((block-title))
  • you use the block reference by typing in the title (the first line) of a block
  • under the hood, logseq will replace the block-title by its block-UUID (that is programatically generated), but the DISPLAYED label in view mode is still the block-title
  • if the user wants to use an alternate LABEL (or alias) for the link, it’s possible to use the [label](block-UUID) format
  • in the RMB menu I think we should replace 'copy Block Refbycopy block-ID | Block UUID`

are there really 3 types of connections ?

The link can currently be shown in three ways in a rendered block:

unfold quote (…)what is displayed: text formatted as a link; reference content is shown only when the link is clicked and the user is taken to the content - this currently includes both Markdown links (page, block, and web) and page links
what is displayed: reference content from another location, formatted to indicate that the content is being transcluded from the another location - this currently includes what we are currently calling “block references”, which already has a different meaning in the glossary—there, a block reference = a block UUID, not a UUID inside (( ))—but this type of transclusion can’t currently be done for Logseq pages; I don’t know if it can be done for files or web pages but people will want it for images at least
what is displayed: what I’ll call an “embed frame” that has a distinct background color; reference content is shown inside the embed frame - this is what we are calling an embed (block, page, or YouTube)

your point 2) is confusing to me : I don’t consider a block ref to be a transclusion.
it’s a LINK that uses the first line (the block-title) as the displayed label.
A transclusion in Nelson’s definition is an embed in logseq’s terms (either a block-embed or a page-embed). I think Roam’s block refs are a confusing reference here as it blurs the line between a link and a transclusion. I much prefer the clear distinction used in logseq or remnote.
When you want to see content : use embeds, when you need a link : use a reference.
it’s similar to web links vs iframe embeds : links vs transclusions

I think it’s simpler to envision it as :

  • internal LINKS : [[page-title]] or [label](page-title) ; ((block-title)) or [label](block-UUID)
  • internal EMBEDS : {{{embed [[page-title]]}}} ; {{{embed ((block-UUID))}}}
  • external links : [label](url) ; [label](file-path); url
  • external embeds : {{{youtube url}}} , etc…

if it ain’t broke, don’t fix it

Most of my comments are written with the current logseq ux/ui in mind : I think it’s better to focus on documenting existing features and explaining how they work, rather than rethinking the logic and changing menu names and other UI labels.

That said, when there is a consensus on super-confusing aspects, change is welcome too.

Of course, this is only my opinion, maybe a majority of users will prefer your suggestions, I’m just stating some alternate povs and trying to provide another perspective on the changes.

For my part, I was really impressed by logseq’s features and ease of use from the start… it just clicked, so I’m probably biased.

I see people confused with the contents section and some menu options, but rarely see questions about the page-ref/block-refs/embeds/linked-refs/unlinked refs workflow.

(sorry for the wall of text, I’ll leave it here and maybe add more constructive comments later on)

2 Likes
3

I really support what @cannibalox said:

Specially this part

page-title is the way to go, the simplier and the most user friendly terms can be the better for new users.

I also fully support the terms used here:

I think a lot of users from other apps coming to Logseq will definitely be familar with the concept of “external” vs “internal” so keeping things with a basic and simple way to describe things is definitely the way to go!

4

Quoting @cannibalox:

we should label concepts according to what the user sees or reads while using the software

I agree, however, note that in Logseq the user sees the page both rendered and in plain text.

Re: page title and page ID, since pages are going to get alphanumeric IDs, I will need to make changes in my post to reflect that.

page-title makes more sense than page-ID (as the word ID is never mentionned in the UI)

I agree that we should try to match the current UI and terms where possible, but the truth is that it is not currently consistent, and now (early development) is the time to intervene to improve concepts and terms so that we remove obstacles so we can help Logseq scale to massive proportions :smile:

re: block-references, @cannibalox makes comments based on how you insert a block reference. The brief poll we took on Discord (n=3 or so) showed that people were split on how they did this. Probably we should define these terms not based on how block refs are inserted by conceptually, based on what they represent.

if the user wants to use an alternate LABEL (or alias) for the link, it’s possible to use the [label](block-UUID) format

Very confusing to me! To me, pages have aliases, but links don’t. Not sure what you mean here.

are there really 3 types of connections ?
your point 2) is confusing to me : I don’t consider a block ref to be a transclusion.
it’s a LINK that uses the first line (the block-title) as the displayed label.

A block can be linked in 3 ways:

  1. [link text](((block-ID))) - displays link text
  2. ((block-ID)) - displays the block title/block content as a native block, but with text styling
  3. {{{embed ((block-UUID))}}} - displays the block title/block content as an embedded block

That’s 3 different plain text link syntaxes, and 3 different rendered results.

A transclusion in Nelson’s definition is an embed in logseq’s terms (either a block-embed or a page-embed).

I don’t know Nelson’s definition of transclusion, but all I meant by it was “showing content from elsewhere in the location where the link is”.

When you want to see content : use embeds, when you need a link : use a reference.

But the current block-ref shows content, and is distinct from a block embed. Am I wrong about that?

I think it’s simpler to envision it as :

  • internal LINKS : [[page-title]] or [label](page-title)

You are combining two types of what you call internal links, and they have to be distinguished because the function differently. First, [[page-title]] cannot have the display text changed without changing the reference, unlike [label](page-title). Second, if the name of the reference is changed, the display text of [[page-title]] will also change, but this is not true of [label](page-title).

if it ain’t broke, don’t fix it

I agree. Of course, the problem is deciding whether it is broke or not. :smile:

Most of my comments are written with the current logseq ux/ui in mind : I think it’s better to focus on documenting existing features and explaining how they work, rather than rethinking the logic and changing menu names and other UI labels.

I would agree if I thought that Logseq was consistent and was working great, but for me, it’s not. As wonderful as it is, it is confusing (at least to me as a non-CS person) and inconsistent. I’m worried that these problems that may seem small now will act as ongoing obstacles to future development, especially to creating a plug-in architecture that can be easily used and expanded. And it is still really early in Logseq’s development so this is the best time to make changes.

I see people confused with the contents section and some menu options, but rarely see questions about the page-ref/block-refs/embeds/linked-refs/unlinked refs workflow.

Truthfully, I think this is because Logseq doesn’t have a good workflow for complex uses of refs, so people aren’t pushing it too much. I have a complex workflow in Roam for writing with lots of citations, integration with a reference manager, moving from fleeting notes to literature notes to permanent notes to paper outlines, and it relies on lots of plug-in functions not available in vanilla Roam, and Logseq is not currently set up to allow similar plug-ins and functionality to flourish.

If Logseq can continue to improve the core experience and not only match Roam for allowing external plug-in development, but actually surpass it by focusing now on getting all of the concepts and terms really consistent so they are easy to document and learn, then it will absolutely attract a huge percentage of current Roam users who hate the DB-only data structure, lack of privacy, lack of encryption, lack of open-source, lack of dev transparency, etc.

Thanks for comments, others please join in also!

5

To me this is a feature request more than a general discussion, and it deserves to be bumped a little bit. When making a reference, there is no reason to force the user to remember whether they made that specific bit of info into a page or a block. The user ends up wasting time and mental resources, which just discourages making references.

Whether that is handled by “everything has a UUID” or “everything has a human-readable unique name” within the files is of less relevance. I personally prefer the human-readable one for interoperability but what matters is that Logseq has a high performance for thought.