It isn't possible to build cycles in your notes

It isn't possible to use can to build your notes to link into a cycle in any way. The can status command should warn you if your working notes form a cycle, and can add will refuse to add notes which form a cycle.

This is for a few reasons. I'll list a few of them, but the largest reason is technical, and under a separate heading

• hyperlinks in can are bidirectional (you can follow them back and forwards easily), so manual cycles in links aren't as useful as they might be otherwise
• avoiding cycles encourages you to build focused, atomic notes. While this is opinionated, it should be widely applicable

Technical Reason

Frankly, the largest reason to avoid cycles across notes is to avoid the need to build 'meta-note' data structures that contain all coreferring notes to be hashed (because can notes are content-addressable). First, the problem. can uses content addressable notes to store your notes in a stable, searchable and easily-syncable way. This means that the names you give your notes aren't the way we store them. Instead, we use a function $\text{addr}$ to find the address, based on a notes content. So for the note $A$, its content is $c(A)$ and it's address is $\text{addr}(A)$.

Consider the notes $A$ and $B$ and the link structure $A \rightarrow B$ $B \rightarrow A$. $A$ refers to $B$ and $B$ refers to $A$ with links like [B](./B.md) (assuming $B$ is stored in b.md when you write it). can replaces these name-based references with the address. Glossing over the fact that we need to perform this replacement on $B$ too and given that $\text{addr}(B)$ is #0, $A$ would then have content looking like the following:

paragraph [B](#0)

If we take $\text{addr}(A)$ now we get #1. We can replace the reference in $B$ to point at $A$'s address to give content like

# B

[A](#1)

But now $B$'s content has changed, and $\text{addr}B$ is #2. This leads to us updating the addresses in a circle, forever.

The best technical solution I could think of to this is the aformentioned 'meta-note'. Cycles like $A$ and $B$ would be put into the same structure $Z$ in a canonical order, and they could refer to the other using this order. They then share an address $\text{addr}(A \land B)$ with the canonical order appended, #0/0 for $A$ and #0/1 for $B$. The problem with this solution is that the cycle could easily be much bigger than two notes, encompassing much of a notebook. A -> B -> C -> D -> A is possible, and this shared metanote could easily slowly consume an entire notebook over time if left unchecked.

I'm not saying this solution will never be used, but for now I don't think it's a good solution even though it works. I'd rather leave the cycle in place for the human author to unwind and allow notes to be stored with an address per note.

Backlinks

• Notebook
  • It isn't possible to build cycles in your notes for now. That means that you can't have a note A linking to a note B, which links back to note A. Or even A -> B -> C -> A. This is to avoid issues with storing notes, and you should be warned if you try to add notes which form a cycle to your notebook. If you find that this happens, try making another note with the content that your cycling notes can refer to. Instead of
• can-add
  • It isn't possible to include cycles in can notes, so can-add should print a warning and exit if a cycle exists in the notes.