A step-by-step tutorial for connecting your documents with typed, bidirectional links — the defining feature of Xudanu's Nelson-style hypertext.
In Xudanu, a link is a typed, bidirectional connection between two passages of text. Unlike ordinary web links (one-way, one-to-one), Xudanu links are:
A transclusion is a special kind of link that copies content from one document into another while maintaining the connection to the original. Think of it as "live quoting" — the quoted text always traces back to its source.
A Comment link from Essay to Reviewer Notes. The blue "C" bar marks the outgoing link; the red "D" marks the disagreement response. The green dashed arrow shows the automatic backlink.
Each link type has a distinct colour and underline pattern. This makes overlapping links readable even in dense documents.
| Type | Colour | Use When |
|---|---|---|
| Comment | Blue, dashed | You want to annotate or add a scholarly note to a passage |
| Reference | Green, solid | Cross-referencing, citing a source, "see this section" |
| Disagreement | Red, long dash | You disagree with a claim and want to link your counter-argument |
| Quotation | Purple, dotted | This passage is a quote from another document |
| See Also | Amber, dash-dot | Related reading path or similar work |
A typed link connects two passages with a semantic relationship. This is the most common type of connection.
Open the document you want to link from. Highlight the passage you want to connect.
Two buttons will appear above the selection: Transclude and Link.
Click the Link button. The Link Creator wizard opens, showing your selected text as the source.
Choose "Link to an entire document". A list of your documents appears. Click the one you want to link to.
Then pick a link type and click Create Link. The link is created immediately — no need to navigate to the other document.
Choose "Link to specific text in another document". The wizard closes and a yellow action bar appears:
Now navigate to the target document (click it in the library sidebar) and highlight the passage you want to link to. The action bar will show link type buttons:
Click the type you want. The link is created!
Press Esc at any time to cancel.
The linked passage now shows a coloured underline and a margin bar. Hover over the marker to see a tooltip with the target document, link type, and excerpt. Click to navigate to the linked document.
A transclusion copies content from one document into another while maintaining the provenance link to the source. This is useful when you want to quote a passage verbatim and have it visible inline.
In the source document, highlight the passage you want to transclude.
Click the Transclude button. A floating badge appears showing the held selection.
Navigate to the destination document. Click Place at cursor on the badge, or simply click in the editor where you want the transclusion inserted.
The transcluded text appears inline with a hatched margin bar, and a provenance chain connects it back to the original source.
Xudanu servers can link to each other. A cross-server link connects a passage on your server to content on a remote Xudanu server. The link persists across restarts and carries the remote content's cryptographic hash for tamper verification.
A cross-server link connects a local passage to remote content. The remote server's content is fetched, verified against a BLAKE3 hash, and cached locally.
As with any link, select the passage in your document and click Link. In the wizard, choose "Link to a remote server".
The tumbler is the Xanadu global identifier for the remote content. It takes one of two forms:
| Format | Example | When to use |
|---|---|---|
| Domain | "alice.example.com".5.3.10.7 | Preferred — human-readable, self-routing via DNS |
| Numeric | 1.5.3.10.7 | When the server has a registered numeric ID in your directory |
The tumbler components are: server . work_id . version . revision . edition
Provide the BLAKE3 content hash (64 hex characters) from the remote server. This is used to verify that the fetched content has not been tampered with. You can find this hash on the remote server's public content API or from a shared reference.
You can add the remote author's name and public key (hex). This information is stored with the link and can be used for attribution and provenance verification. If omitted, the author defaults to "unknown".
The link is created. The remote server's content is fetched on demand when the link is resolved, verified against the stored hash, and cached locally for fast subsequent access.
"server.address".work_id.v.revision.edition is preferred because it's self-routing — the client can look up the server via DNS. The numeric format server_id.work_id.v.revision.edition requires the server ID to be registered in your local server directory.
You can manage existing links from the Connections panel on the right side of the screen. Each link shows:
To use the management controls:
When links exist on a passage, you will see three visual elements:
Anatomy of a link marker: left margin bar (outgoing), coloured underline (type style), right margin bar (incoming), and invisible hit zone for interaction.
| Position | Meaning | Colour |
|---|---|---|
| Left margin | This document links OUT to another document | Link type colour |
| Right margin | Another document links IN to this passage | Green |
| Left margin (dashed) | Cross-server link OUT to a remote server | Amber, dashed border |
Links to remote servers display with a distinct amber dashed border pattern to distinguish them from local links. The marker tooltip shows the remote server's address, tumbler, and author information. If the remote content has been cached locally, clicking the marker navigates to a read-only view; if not yet cached, the server fetches and verifies it on first access.
Multiple links on the same passage are rendered in separate vertical lanes, each offset by 2px so all remain visible. When five or more links overlap in a region, they collapse into a single amber density pill showing the count. Click the pill to expand the cluster.
When a link has a description, a coloured description box appears in the right margin showing the link type label and the description text. A dotted connecting line runs from the box to the source text, anchoring to the underline of the linked passage (the bottom of the text, not the centre). When multiple links overlap, the connecting lines use lane separation so each remains distinguishable.
Hovering over any link marker (margin bar, underline hit zone, or density pill) shows a tooltip with the target document title, link type, text excerpt, and action buttons: Go to, Trace provenance, and a red × Delete link button. The delete button works for any typed link — no need to open the Connections panel.
The Connections panel on the right side of the screen gives you a unified view of all connections for the current document:
| Section | What It Shows |
|---|---|
| Transclusions | Inline transcluded content from other documents (amber border) |
| Links | Typed links you created from this document (blue border) |
| Backlinks | Links from other documents pointing into this one (green border) |
| Cross-server | Links to content on remote Xudanu servers (amber dashed border) |
Use the dropdown at the top to filter by type. Pin important connections with the star (☆) to keep them at the top. Click any item to navigate to the connected document.
| Key | Action |
|---|---|
| Esc | Cancel pending link/transclusion creation |
| Ctrl + K | Open search |
| Click marker | Navigate to the linked document |
| Double-click marker | Jump to linked document and show its connections |
| Hover marker | Show tooltip with target, type, excerpt |