Images, links, and citations

Use an image to explain what someone should recognize, a link to connect related pages, and a citation to show where a statement came from.

Add an image

1. Open a Context page in the editor and place the cursor near the relevant sentence.
2. Use Image / Upload image, or paste or drop an image into the editor.
3. Check the Image upload queue and wait for success.
4. Replace generic alternative text with a useful description, such as “Launch checklist with the reviewer field highlighted.”
5. Read the preview, then save the page.

Accepted image types, file size, and batch limits come from the current workspace policy. Follow the displayed limits instead of assuming that every image extension works. Uploads belong to the page; they are distinct from uploading a reference file to Library.

If an upload fails, use Retry or Remove. An unresolved upload blocks saving, because a page must not save a broken insertion slot as if it were a completed image. Browser-hosted external images can also fail if their host removes them or blocks access.

Use Manage page media to see images retained by the page. An image referenced by a current or retained historical version cannot be deleted from that dialog. Removing it from today's text does not necessarily make it unused. Deleting an unused upload is permanent. To review uploads across the whole workspace, use Settings → Attachments.

Review and clean up uploaded files

Settings → Attachments, under This workspace, lists the images, audio and video uploaded into this workspace's pages. Every member can open it. The list includes only files on pages you can read, never private uploads in someone else's unsaved draft.

Role	Filters	Files shown
Owner	All (default), Mine, Unused	Uploads by every member
Editor, Viewer	Mine (default), Unused	Only your own uploads

Each row shows the file name, type and size, a state, the page (a link that opens it), the uploader and the upload time. You marks your own uploads. Thumbnails appear only for images you are allowed to view; other rows show a placeholder. Search by file name, use Refresh to reload the list, and use Load more to see older files.

State	Meaning
In use	The page's current published version or latest draft uses the file.
History only	Only older versions of the page use it.
In an open draft	It was uploaded into an edit that is still open, so dtxWiki keeps it.
Unused	No version of the page uses it.

Delete unused files

Editors and Owners can delete files that no page version uses; Viewers can only look. Files marked In use or History only have no Delete button.

1. To delete one file, choose Delete on its row, then choose Delete attachment in the confirmation that warns the deletion cannot be undone.
2. To delete several, choose Unused. Tick individual files, or tick Select all to choose every unused file loaded so far, then choose Delete selected and Confirm deletion. Select all covers only files already loaded, so choose Load more first if you also want older ones.

Expected result: the deleted rows disappear, and a bulk deletion reports a result such as 3 deleted, 0 failed. If someone used or changed a file after you loaded the list, dtxWiki refuses to delete it, says why, and reloads the list. A file that any page version still uses, including a private draft you cannot see, is never deleted. Deletion cannot be undone; only a server backup can bring a file back.

Automatic cleanup of unused files

The Unused file auto reclamation card shows this workspace's rule, for example Unused file retention: 7 days with Using server default or Workspace override, or Unused file auto reclamation is off. While cleanup is on, unused files older than the retention period, counted from the upload time, are permanently deleted during periodic cleanup. Files that any page version uses, or that an open edit holds, are never removed this way. An image uploaded during an edit but never saved into the page becomes unused once that edit is submitted, published or discarded, and is removed after the period has passed.

An Owner can change the rule:

1. In the card, open Change settings.
2. Tick or clear Enable auto reclamation. To keep cleanup on, enter a whole number in Retention period and choose Days or Hours under Unit. To follow the server again, choose Use server default.
3. Choose Save policy. If you turn cleanup on or shorten the period, dtxWiki warns that existing unused uploads may be deleted in the next cleanup; choose Save and apply to continue.

Expected result: the card shows the new rule with Workspace override, or Using server default after you return to the default. The new rule applies to cleanup that starts after you save. The server default is 7 days unless the server administrator changed it.

Server administrators also get an All workspaces scope on this screen. It lists attachment details from every workspace, without previews. See Privacy and safe sharing.

Connect two Context pages

Create an FAQ page, then link to it from Launch plan:

1. Choose Wikilink, or type [[ in the page body.
2. Select FAQ from the suggestions.
3. Save, publish when appropriate, and follow the link in the reader.

See [[faq|FAQ]] for common questions.

The target slug above is an example. Select the actual page suggestion instead of guessing its identifier. A regular web link uses the Link control and a URL. Wikilinks connect workspace knowledge and can appear in backlinks and the local graph.

If several pages have the same name, choose the intended target. An internal link still respects the recipient's workspace access.

Add a reference

Use the fictional Launch brief in Library to support a statement in Launch plan:

1. Open Launch plan in the Context editor and inspect the source you intend to cite.
2. Open References (N), then choose Add reference. The Citation toolbar action, /cite, and @cite{ also open Choose a reference.
3. Search by title or text, or paste a document address. Use Document type to choose Context, Library, or Agent, then select the exact document.
4. Add Note (optional) if it will help a reader understand why you used this source.
5. Choose one of the two actions below and inspect the References panel.

Action	Result
Cite in text	Inserts an in-text citation at the cursor. The reader shows it as a numbered citation linked to References. A note is retained with the reference registration.
Add to references only	Registers the document and optional note without inserting a body marker. The panel identifies it as Not cited in text.

The editor inserts a document address, such as @cite{/p/<workspace_id>/<page_id>} for Context or @cite{/workspaces/<workspace_id>/library/items/<item_id>} for Library. Select a real document; do not invent a slug, hash or citation key. Agent references are supported too. A reference documents which material you used; read that material before treating it as support for a claim.

Turn an existing link into a citation

Select an internal document link in the editor, open References (N) and choose Mark selected link as citation. The link's label remains in the text with an address-based citation marker beside it. This is useful when a plain navigation link should also identify supporting material. A missing or unsuitable selection prompts you to select an internal document link first.

Save, publish and inspect

Save the draft and wait for its status. Reference registrations belong to that page version; they do not publish the page. When the version is published, dtxWiki combines its in-text citations and explicitly registered references. The reader shows numbered citations and a References section, including entries that are not cited in the body. Citation return links take you back to the corresponding passage.

Graph citation relationships use those saved publication references, including supported Agent targets. Saving a draft alone does not add lines to the current published graph. Publish the source version, then check the document graph or Knowledge Map, subject to target availability and graph filters. A graph line does not certify that the source proves your statement.

If you share the page publicly, its References section follows the anonymous reader's access. A target that is not publicly available appears as Document unavailable, without its private title, note or destination. Anonymous references can open only eligible Context pages with their own web exposure enabled; Library and Agent references remain unavailable on public pages. Publishing the citing page does not expose its private source. Use Share → Preview published version and check the public URL while signed out.

Correct an unresolved citation or uncertain save

The combined list supports at most 500 distinct referenced documents per page. Repeated citations to the same document use one reference entry. Replace old @cite{key} tokens or unsupported addresses by choosing a real document. Unresolved citation in Lint means that the marker did not identify a supported document in this workspace; an unresolved marker is not a registered citation.

Remove reference removes the explicit registration, but any in-text citation remains until you remove it from the body. To remove the reference completely, check both the panel and the text, save, and publish the changed version when appropriate. Changes to reference registrations or notes also appear under Reference changes in review and history comparisons.

If a reference request fails or its result is uncertain, keep your writing in the editor. Use Retry reference change, or Check status and finish reference request when offered, before saving or publishing again. If the screen says references were saved but the list could not be reloaded, reload the list to inspect the server's result. A retry-status notice is different from a failed publication.

Add a small diagram

Use a table to compare items and a Mermaid diagram to explain a short relationship. Keep screenshots for controls or scenes the reader should recognize. The reader can render the following Mermaid text; copy the whole block into the page body:

```mermaid
flowchart LR
  Brief[Launch brief] --> Plan[Launch plan]
  Plan --> Review[Human check]
```

To explain who sends a request and what happens next, use a sequence diagram. This example describes a fictional review conversation; it does not send a real review request:

```mermaid
sequenceDiagram
  autonumber
  participant Author as Page author
  participant Reviewer as Human reviewer
  Author->>Reviewer: Request a review
  Reviewer-->>Author: Ask for a correction
  Author->>Reviewer: Submit the corrected draft
```

Read the example from top to bottom: the author requests a review, the reviewer asks for a correction, and the author submits the corrected draft. autonumber numbers the messages. In v0.2.1, sequence message lines, arrowheads, and message numbers remain visible in both the page and the expanded viewer.

1. Paste the complete block into a Context page, including the opening and closing lines of three backticks.
2. Switch to Reading to check the diagram before publishing. On a wider editor you can also use Split; that option is hidden when the editor is narrow.
3. Choose the expand icon beside the diagram to open the larger viewer. Its accessible name is Expand Mermaid diagram. The viewer has icon buttons named Zoom in, Zoom out, Reset zoom, and Close Mermaid zoom. You can also use +, -, and 0 to zoom or reset, and Esc to close it. The title Diagram viewer is announced to screen readers; it is not a visible heading.

Label explanation diagrams so readers can distinguish them from actual product screenshots, and keep a plain-text explanation beside them. If Mermaid diagram could not be rendered. appears, the original code remains visible. Return to the editor, check the syntax and matching code fences, then preview again.

Stable destinations and index references

Copy a Context Workspace link such as /p/<workspace_id>/<page_id> instead of reconstructing a slug. Renaming a page does not retarget its pinned identity. Links to another workspace still require that membership; an unavailable reference can offer a safe return or workspace choice. Public pages activate only destinations confirmed as exposed published Context pages.

Editor previews show the opened page's known links immediately and check newly introduced links after typing pauses. A checking indicator is not a saved edit. The unsaved body is not sent or replaced by that check. An unavailable or uncertain fragment can remain unverified even when its document is accessible.

System indexes can contain dtxwiki://index/<kind>/<id> destinations. Their formatted/source switch lets you inspect the exact server Markdown; only verified matching entries navigate. On authored Context saves and Agent draft writes, exact readable index references become supported canonical links even in suggestion mode or with formatting off. Hidden/missing targets retain their source and a diagnostic. Restores, copied versions and historical bodies retain their original text.

For optional fixing of other authored links, see Lint settings. For citations, use the document picker and publish the version to update graph relationships. MCP clients register references with cite; see the API and MCP reference.

Next: Create and edit Context pages or Review and history.

Implementation reference: editor commands and completions, page media management, image rendering, Mermaid rendering, diagram viewer controls, attachment list and deletion, unused-file cleanup settings, cleanup rules, reference picker, reference storage and publication.