Zum Inhalt springen

Rich Text ​

Beschreibungen, Rich-Text-Properties, Kommentare und Wiki-Seiten sind Rich Text: formatierter Text mit Erwähnungen, Verweisen auf Items und Seiten, Bildern und Dateien. werkbuch speichert ihn als JSON in der Form des Editors (Tiptap) und liest und schreibt ihn auch als Markdown, damit API und Agenten mit schlichtem Text arbeiten. HTML, das jemand einfügt oder schickt, zeigt werkbuch nie so, wie es kam; dargestellt werden nur die Knoten, die werkbuch kennt.

Stufen des Editors ​

Es gibt einen Editor in drei Stufen. Jede Stufe zeigt, was an ihren Ort passt:

StufeWoBlöcke
KommentarKommentareText, Listen, Zitate, Code, Links, Tabellen (auch im /-Menü), Erwähnungen, Verweise, Bilder und Dateien
BeschreibungBeschreibungen von Items und Vorlagen, Rich-Text-PropertiesDazu Überschriften (drei Ebenen) und Checklisten
SeiteWiki-SeitenDazu Trennlinien

Ein Text mit Blöcken, die seine Stufe nicht kennt (eine Checkliste in einem Kommentar), zeigt deren Text als Absätze. mod+enter speichert bzw. sendet; Beschreibung, Rich-Text-Properties und Wiki-Seiten speichern außerdem nach einer kurzen Pause und beim Verlassen des Felds von selbst.

Blöcke und Kürzel ​

Ein / am Zeilenanfang oder nach einem Leerzeichen öffnet das Blockmenü (direkt nach fettem Text, einer Erwähnung oder einer Datei bleibt es ein Schrägstrich). Tippen grenzt die Liste ein (auch über Wörter wie „todo“ für eine Checkliste), die Pfeiltasten wählen, enter oder tab macht aus der Zeile den Block, esc schließt das Menü. Jeder Eintrag nennt sein Markdown-Kürzel, das auch beim Tippen wirkt:

BlockKürzel beim Tippen
Überschrift 1 bis 3# , ## , ###
Liste-
Nummerierte Liste1.
Checkliste[ ]
Code``` (mit Sprache: ```php)
Zitat>
Trennlinie (nur Seiten)---

Bild oder Datei im Menü öffnet die Dateiauswahl des Browsers. Code wird für Bash, CSS, Diff, JavaScript, JSON, Markdown, PHP, Python, Shell, SQL, TypeScript, XML und YAML hervorgehoben; ohne Sprache rät werkbuch eine für die Anzeige, der Text bleibt, wie du ihn getippt hast. Fett, kursiv, durchgestrichen, Code im Text und Links gehen mit den üblichen Markdown-Zeichen (**, *, ~~, `) und Tasten. Links behalten nur http, https und mailto.

Tabellen bearbeiten ​

Steht der Cursor in einer Tabelle, sitzt an ihrer oberen Kante rechts der Knopf Tabelle; alt+F10 öffnet sein Menü auch direkt aus dem Text. Darin fügst du Zeilen darüber oder darunter und Spalten links oder rechts ein, löschst die Zeile oder Spalte des Cursors oder die ganze Tabelle und schaltest Kopfzeile und Kopfspalte an und aus. Kopfzeile und Kopfspalte bleiben die erste Zeile und die erste Spalte, auch wenn du davor etwas einfügst. Eine Tabelle aus einer Zeile hat keine Kopfspalte. Die letzte Zeile und die letzte Spalte bleiben; lösche dann die Tabelle. Nach jedem Befehl und mit esc geht der Fokus an dieselbe Stelle im Text zurück. Dieselben Befehle stehen im /-Menü, solange der Cursor in einer Tabelle steht (Gruppe „Tabelle“). Eine Spalte ist mindestens 6 rem breit: Eine Tabelle, die breiter als ihr Text ist, scrollt in der Vorschau oder am Handy waagerecht in ihrem Rahmen. Zellen verbinden und einzelne Kopfzellen bietet der Editor nicht an: Markdown trägt beides nicht (siehe Tabellen unter Markdown).

Erwähnungen ​

@ öffnet eine Liste der Personen und Bots, die im Projekt erwähnt werden können: seine aktiven Mitglieder und Personen, die Org-Admins sind. Ein Bot nur, wenn er Mitglied des Projekts ist, auch der Standard-Bot. Tippen grenzt die Liste über Name oder Handle ein. Eine Erwähnung zeigt den aktuellen Handle des Kontos, auch nach einer Umbenennung; ein deaktiviertes Konto ist als solches markiert.

Wer in einem Item oder Kommentar erwähnt wird, beobachtet das Item danach, auch wenn er es abbestellt hatte, und bekommt eine Benachrichtigung. Ein erwähnter Bot bekommt das Event bot.mentioned. Es zählen nur neu Erwähnte: Wer einen Text bearbeitet, in dem eine Erwähnung bleibt, erwähnt niemanden noch einmal, und wer sich selbst erwähnt, zählt nicht. Eine Erwähnung in einer Wiki-Seite bleibt eine Erwähnung, benachrichtigt aber niemanden.

Die Erwähnung von jemandem, der im Projekt nicht erwähnt werden kann, etwa weil er es verlassen hat, wird beim Speichern zu Text @handle. Eine Erwähnung, die schon im Text stand, bleibt eine Erwähnung.

Verweise ​

# sucht die Items und Wiki-Seiten, die du siehst, mit derselben Suche wie die Befehlspalette: Items über den Key (auch einen früheren), den Titel und den Text, Seiten darunter über Titel und Text. Ein Verweis auf ein Item zeigt dessen Typ und aktuellen Key, den Titel für Screenreader, und führt beim Lesen zum Item; ein Verweis auf eine Seite zeigt ihr Emoji und ihren aktuellen Titel und führt zur Seite. Nennst du in der Beschreibung, einem Rich-Text-Feld oder einem Kommentar eines Items ein anderes Item neu, verknüpft werkbuch beide außerdem mit dem eingebauten Relationstyp „verwandt“, wenn du das Item bearbeiten darfst (die Automatisierung „Erwähnte Items verknüpfen“, standardmäßig an).

werkbuch speichert nur die ULID des Items bzw. der Seite, nie Key oder Titel. Wer den Text liest, sieht den Verweis so, wie er darf: Ein Item oder eine Seite, die er nicht sieht, steht als verborgen da, ohne Key und Titel, in der Oberfläche, in der API und in Mails. Beim Speichern kannst du nur auf Items und Seiten verweisen, die du siehst; ein Verweis, der schon im Text stand, bleibt, auch auf eins, das du nicht siehst.

Bilder und Dateien ​

Füge einen Screenshot oder ein im Browser kopiertes Bild ein, ziehe Dateien in den Editor oder wähle sie mit Bild oder Datei im /-Menü. Jede Datei zeigt beim Hochladen ihren Fortschritt, und du kannst weitertippen. Bilder stehen im Text. Ein Klick auf ein Bild (mit strg oder cmd öffnet sich das Original in einem neuen Tab) oder enter auf einem ausgewählten Bild im Editor zeigt es groß: das Original, sein Alternativtext und Dateiname, Originalgröße, Original öffnen und Herunterladen; ← und → blättern durch die Bilder desselben Texts, esc schließt und geht zurück zum Bild. Im Editor hat ein ausgewähltes Bild einen Reiter Bild (alt+F10): groß anzeigen, Alternativtext bearbeiten (auch per Doppelklick), Original öffnen oder herunterladen, entfernen. Jede andere Datei ist ein Chip mit Name und Größe; ein Klick lädt sie herunter.

  • Formate: werkbuch erkennt den Typ einer Datei an ihrem Inhalt, nie an ihrem Namen oder an der Angabe des Browsers. Nur PNG, JPEG, GIF, WebP und AVIF erscheinen im Text; alles andere, auch SVG und PDF, kommt als Download (Content-Security-Policy: sandbox, nosniff). HTML oder Markdown mit der Adresse eines Bilds (<img src>, ![](https://…)) wird nie ein Bild; sein Alternativtext bleibt als Text.
  • Größe: höchstens ATTACHMENTS_MAX_MB je Datei, standardmäßig 25 MB. Eine größere Datei lehnt der Browser ab, bevor er sie hochlädt; über die API ist sie ein 413. Solange ein Upload läuft, fragt das Verlassen der Seite nach; wer den Text schließt, bricht den Upload ab und bekommt das gesagt.
  • Vorschauen: Für PNG, JPEG und WebP rechnet werkbuch im Hintergrund (Queue media) eine Vorschau von höchstens 1600 × 1600 Pixeln; bis sie da ist, zeigt es das Original. GIF behält seine Animation, AVIF erscheint ohne Vorschau.
  • Wer: Bilder und Dateien in einen Text einfügen darf, wer kommentieren darf, auch Viewer. Die Dateiliste eines Items braucht das Recht, das Item zu ändern (siehe Work Items).
  • Wer sie sieht: Eine Datei bekommt nur, wer das Item (oder das Item des Kommentars) sieht, zu dem sie gehört, bzw. das Projekt ihrer Wiki-Seite; für alle anderen ist sie ein 404, als gäbe es sie nicht.

Ein Upload gehört niemandem, bis der Text gespeichert ist, der ihn nennt; dann gehört er diesem Text. Ein Text darf auch ein Bild eines anderen Texts desselben Projekts zeigen (aus einer Beschreibung in eine andere kopiert); das Bild bleibt bei seinem ersten Text. Ein Bild eines anderen Projekts oder den Upload einer anderen Person, den noch kein Text übernommen hat, kann er nie nennen.

Bilder und Dateien, die aus einem Text verschwinden, bleiben erhalten, damit History und Rückgängig funktionieren. Das Aufräumen entfernt sie später.

Markdown ​

Über die API kommt jeder Rich Text in zwei Formen: Markdown (description, body, content, values_markdown) und Tiptap-JSON (description_json, body_json, content_json, values). Geschrieben wird eine der beiden, nie beide. Markdown liest werkbuch als GitHub-Markdown; HTML darin bleibt Text. werkbuch schreibt jeden Knoten in genau einer Form, ein gelesener und unverändert zurückgeschickter Text bleibt also derselbe.

WasMarkdown
Erwähnung@mara
Verweis auf ein ItemWEB-123
Verweis auf ein Item, das der Leser nicht sieht[hidden](item:<ulid>)
Verweis auf eine Seite[Titel](page:<ulid>), mit dem aktuellen Titel
Verweis auf eine Seite, die der Leser nicht sieht[hidden](page:<ulid>)
Bild![Alternativtext](attachment:<ulid>)
Datei[angebot.pdf](attachment:<ulid>)

Schreiben über REST ​

Für Markdown und JSON gelten dieselben Regeln, geprüft für das Konto, das schreibt:

Du schreibstErgebnis
@handle eines Kontos, das im Projekt erwähnt werden kannEine Erwähnung.
@handle ohne Zugriff auf das Projekt, unbekannt oder deaktiviertBleibt Text.
WEB-123 eines Items, das du siehst (auch mit früherem Key)Ein Verweis mit dem aktuellen Key.
WEB-123 eines Items, das du nicht siehst oder das es nicht gibtBleibt Text; niemand erfährt, ob es das Item gibt.
[hidden](item:<ulid>), das schon im Text standBleibt ein Verweis.
[x](item:<ulid>) eines Items, das du nicht siehst, neu im TextBleibt Text: x.
[Titel](page:<ulid>) einer Seite, die du siehstEin Verweis; werkbuch behält nur die ULID und schreibt beim Lesen den aktuellen Titel.
[Titel](page:<ulid>) einer Seite, die du nicht siehst, neu im TextBleibt Text: Titel.
attachment:<ulid> des Projekts, das ein Text besitzt, oder dein eigener UploadEin Bild bzw. eine Datei.
attachment:<ulid> eines anderen Projekts oder eines fremden Uploads ohne Text422 am Feld, das den Text schickte; nichts wird gespeichert.

In Code-Blöcken, Code im Text, Linktexten und Alternativtexten wird nichts als Erwähnung oder Verweis gelesen: `@mara` und [WEB-123](https://example.com) bleiben, wie sie sind. Ein Backslash hält Text davon ab, eins zu werden: \@mara, WEB\-123. Schreibt werkbuch Markdown, setzt es diesen Backslash vor Text, der auf dem Rückweg sonst zur Erwähnung oder zum Verweis würde.

Tabellen ​

Markdown kennt eine Art Tabelle: die erste Zeile ist die Kopfzeile, keine Spalte ist eine Kopfspalte. So schreibt werkbuch jede Tabelle. Schickst du Markdown zurück, behält jede Tabelle Kopfzeile und Kopfspalte, die der Text vorher hatte. Hat dein Markdown so viele Tabellen wie der gespeicherte Text, übernimmt die erste Tabelle sie von der ersten gespeicherten, die zweite von der zweiten und so weiter, solange beide gleich viele Spalten haben. Fügst du eine Tabelle ein oder entfernst eine, ordnet werkbuch Tabellen nur vom Anfang und vom Ende des Texts her zu, und nur solange eine Tabelle gleich viele Spalten und denselben Text in der ersten Zeile hat wie die gespeicherte; an der ersten Tabelle, die abweicht, hört es auf, und die Tabellen dazwischen gelten so, wie Markdown sie schreibt. Ein Layout wandert so nie auf eine andere Tabelle, aber eine Tabelle, die du zwischen andere einfügst oder deren erste Zeile du in derselben Anfrage änderst, kommt mit Kopfzeile und ohne Kopfspalte zurück. Neue oder entfernte Zeilen ändern am Layout nichts; mit einer anderen Zahl Spalten oder in einem neuen Text gilt die Tabelle so, wie Markdown sie schreibt. Eine Tabelle ohne Kopfzeile bekommt deshalb über Markdown nie eine: Kopfzeile und Kopfspalte schaltest du im Editor oder per JSON um. Einzelne Kopfzellen und Zellen über mehrere Zeilen oder Spalten trägt Markdown nicht; sie gehen verloren, wenn Markdown zurückkommt. JSON (*_json) behält alles.

REST ​

Lesen braucht ein Token mit read, Schreiben eins mit write. Ein Kommentar oder Anhang eines Items, das du nicht siehst, ist ein 404.

AnfrageAntwort
GET /api/v1/work-items/{item}/commentsDie Kommentare des Items, älteste zuerst, mit cursor und per_page.
POST /api/v1/work-items/{item}/comments201 mit dem Kommentar; body (Markdown) oder body_json.
GET, PATCH, DELETE /api/v1/comments/{id}Der Kommentar; den eigenen ändern; den eigenen löschen (Projekt-Admins und Org-Admins löschen jeden, 204).
PUT, DELETE /api/v1/comments/{id}/reactionsEigene Reaktion hinzufügen oder zurücknehmen, {"emoji": "👍"} (bei DELETE im Body oder als ?emoji=); beides lässt sich wiederholen und antwortet mit dem Kommentar.
POST /api/v1/attachmentsHochladen (Multipart): project_id, kind (inline für Texte, file für die Dateiliste mit work_item_id), file. 201.
GET, DELETE /api/v1/attachments/{id}Die Daten eines Anhangs; ihn löschen (204).
GET /attachments/{id}Die Datei selbst; ?download=1 immer als Download, /attachments/{id}/preview die Vorschau.
GET /api/v1/mentions?project=WEB&q=maWer im Projekt erwähnt werden kann, beste Treffer zuerst.
GET /api/v1/references?items=<ulid>,<ulid>&pages=<ulid>Die Items und Seiten hinter Verweisen (zusammen höchstens 100), nur die, die du siehst, ohne zu sagen, welche fehlen.
GET /api/v1/work-items/{item}?include=attachmentsBettet die Dateiliste des Items ein.

Die Datei-Route nimmt auch ein Bearer-Token mit read, so laden Skripte Dateien herunter. Hochladen geht höchstens 60-mal je Minute und Konto.

Einen Kommentar schreiben ​

bash
curl -X POST https://werkbuch.example.com/api/v1/work-items/WEB-47/comments \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"body": "Auf Staging behoben, @mara schaust du drüber? Gleiche Ursache wie WEB-42.\n\n- Formular sendet einmal\n- Mail kommt einmal"}'

Die Antwort (201):

json
{
  "data": {
    "id": "01m6b3h0xq7tn2c5d8e9f4g6hj",
    "work_item_id": "01m6akyecnp503vn6jmb8sp249",
    "author_id": "01m6akx65qgwfz2m2tz3bpt7st",
    "body": "Auf Staging behoben, @mara schaust du drüber? Gleiche Ursache wie WEB-42.\n\n- Formular sendet einmal\n- Mail kommt einmal",
    "body_json": { "type": "doc", "content": ["…"] },
    "created_at": "2026-11-03T09:12:44.318204Z",
    "edited_at": null,
    "reactions": []
  }
}

In body_json ist @mara ein Knoten {"type": "mention", "attrs": {"id": "<ulid>", "label": "mara", "mentionSuggestionChar": "@"}} und WEB-42 ein Knoten {"type": "reference", "attrs": {"id": "<ulid>", "kind": "item", "label": null, "mentionSuggestionChar": "#"}}. Eine Änderung (PATCH mit body oder body_json) markiert den Kommentar als bearbeitet; die History behält die frühere Fassung, bis der Kommentar gelöscht wird. Ein Kommentar, der nach den Regeln leer ist, ist ein 422 an body.

Eine Datei hochladen ​

Erst das Bild hochladen, dann im Text nennen:

bash
curl -X POST https://werkbuch.example.com/api/v1/attachments \
  -H "Authorization: Bearer <token>" \
  -F project_id=WEB \
  -F kind=inline \
  -F file=@screenshot.png
json
{
  "data": {
    "id": "01m6b3k2r5s8t1v4w7x0y3z6ab",
    "project_id": "01m6akx72yptw2aw6n30m5fg0a",
    "owner": null,
    "kind": "inline",
    "filename": "screenshot.png",
    "mime": "image/png",
    "size": 48213,
    "inline": true,
    "url": "/attachments/01m6b3k2r5s8t1v4w7x0y3z6ab",
    "preview_url": null,
    "uploaded_by": "01m6akx65qgwfz2m2tz3bpt7st",
    "created_at": "2026-11-03T09:14:02.000000Z"
  }
}
bash
curl -X PATCH https://werkbuch.example.com/api/v1/work-items/WEB-47 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"description": "Das zweite Senden sieht man hier:\n\n![Netzwerk-Tab](attachment:01m6b3k2r5s8t1v4w7x0y3z6ab)"}'

Ab dann gehört das Bild zur Beschreibung von WEB-47 (owner {"type": "work_item", …}). Für die Dateiliste eines Items schickst du kind=file und work_item_id=WEB-47: Die Datei gehört dann sofort dem Item, und seine History nennt sie.

Fehler ​

Eine Datei über der Grenze, auch wenn PHP sie schon verworfen hat, bevor werkbuch sie sieht:

json
{
  "type": "urn:werkbuch:problem:payload_too_large",
  "title": "Anfrage zu groß",
  "status": 413,
  "detail": "Uploads können höchstens 25 MB groß sein.",
  "reason": "payload_too_large"
}

Ein Text, der ein Bild eines anderen Projekts oder den Upload einer anderen Person nennt:

json
{
  "type": "urn:werkbuch:problem:validation_failed",
  "title": "Validierung fehlgeschlagen",
  "status": 422,
  "detail": "Die Eingabe ist nicht gültig.",
  "reason": "validation_failed",
  "errors": { "description": ["Der Text nennt ein Bild oder eine Datei, die er nicht verwenden darf: lade sie in diesem Projekt neu hoch."] }
}

Ein Bild oder eine Datei zu löschen, die zu einem Text gehört, ist ein 409 mit reason: attachment_inline: Es geht mit seinem Text. Einzeln gelöscht werden nur Dateien der Dateiliste, und nur von jemandem, der das Item ändern darf; eine Datei der Liste, die ein Text des Projekts nennt, verlässt die Liste und bleibt als Datei dieses Texts. Ein Text, der noch ein inzwischen verschwundenes Bild oder eine verschwundene Datei nennt, lässt sich speichern: Das tote Bild bzw. die tote Datei verschwindet dabei aus ihm. Kommentare und Reaktionen an einem archivierten Item oder in einem archivierten Projekt lehnt werkbuch mit 409 ab (archived, project_archived).

Aufräumen ​

Zwei Dinge halten Uploads klein:

  • Uploads, die kein Text übernommen hat (ein Bild in einem Kommentar, der nie abgeschickt wurde): Ein Job des Schedulers entfernt sie stündlich, sobald sie älter als 24 Stunden sind. Der Browser löscht Uploads nie selbst, denn ein Text kann schon mit ihnen gespeichert sein.
  • Bilder und Dateien, die kein Text mehr nennt: php artisan app:prune-attachments --dry-run --min-age=30 listet die Bilder und Dateien, die kein aktueller Text ihres Projekts nennt (Beschreibungen, Rich-Text-Werte, Kommentare, Wiki-Seiten und ihre Versionen, Vorlagen) und die älter als das Mindestalter in Tagen sind; ohne --dry-run entfernt es sie. Ein Bild, das nur noch eine Version einer Wiki-Seite zeigt, bleibt, denn Versionen lassen sich wiederherstellen; Bilder, die nur eine ältere Fassung in der History eines Items zeigt, gehen dabei, wähle das Mindestalter danach. Dateien der Dateiliste räumt es nie ab.

Wer ein Item löscht, löscht seine Dateien und die seiner Kommentare, wer einen Kommentar löscht, dessen Dateien, wer eine Wiki-Seite löscht, die ihres Teilbaums, wer eine Vorlage löscht, ihre eigenen, wer ein Projekt löscht, alle; ein Bild, das ein anderer Text des Projekts noch zeigt, bleibt und gehört dann diesem Text. Dateien gehen erst, wenn die Änderung gespeichert ist: Scheitert sie, geht nichts verloren. Mehr unter Entwicklung.