flows.md · documentation

Links#

Three ways to link one thing to another without writing the whole address, and what each reader sees.

A page by its name#

Write another page's name in double brackets, as notes apps do:

[[Roadmap]]
[[Roadmap|this quarter's plan]]
[[Roadmap#Next steps]]
[[~/work/roadmap]]

When the page is saved, each one that names one page becomes an ordinary link to its address — [this quarter's plan](/@ana/work/roadmap) — so the text reads the same in any Markdown reader. Moving the page rewrites the link like any other.

A name is a page's title or the last part of its address, in the same space. The nearest one counts: first the pages inside this one, then the ones beside it, then beside each page above. When none is that near, the only page of the space with that name counts. Two equally near are not guessed: the [[…]] stays as written, and whoever wrote it through the MCP gets the candidates.

Only pages the writer may open count, and the link's words are the writer's, never the other page's title. In a table, write the pipe as [[Roadmap\|the plan]]. Inside code nothing changes.

Words that become links by themselves#

A space can say that some words name things elsewhere: #511 is a pull request, TICK-42 a ticket. Make a collection named link-patterns in the space:

```@schema collection:link-patterns
pattern text
url text
scope text
use text
active boolean default:true
```

and one row per pattern:

pattern	url	scope
#{num}	https://github.com/acme/app/pull/{num}
TICK-{num}	https://tickets.example.com/browse/TICK-{num}
#{num}	https://github.com/acme/site/pull/{num}	~/site

{num} is a number; {id} is letters and digits. The page's text never changes: the link appears when the page is shown, so fixing a pattern fixes every page at once. A word glued to it (issue#511, #511a), anything inside code, and a link you already wrote stay as they are.

With scope, the pattern applies to that page and the pages inside, and the nearest wins — like a theme. A row with only use: /@other brings in another space's patterns, when they are public or whoever wrote the row may read them. The collection must accept rows only from the space's writers; a row that could never become a link is refused when written, with the reason.

Who sees what#

• Linked from. At the end of each page, the pages that link to it — only the ones the reader may open. The MCP answers the same in backlinks.
• A link to a page the reader may not open shows as the writer's words, without a link, like a link to a page that does not exist. The closed page's address and title never reach someone who cannot open it.
• A [[…]] that found no page shows as its words, and becomes a link by itself once the page exists for the reader.