Sign in

Markdown

Markdown ist ein weit verbreitetes Klartextformat, das sich in jedem Editor sauber liest und in allen Tools einheitlich gerendert wird. Wikilayer speichert den Text jedes Knotens als Markdown, parst ihn mit goldmark + GFM und ergänzt einige projektspezifische Erweiterungen für Querverweise und eingebettete Hinweisboxen.

CommonMark und GFM

Alles aus CommonMark plus GitHub-Flavored Markdown, mit einer Ausnahme: Eine Überschriftenzeile im Text wird abgelehnt, denn jede Überschrift gehört zu einem eigenen Knoten, und der Renderer erzeugt sie aus dessen Titel.

Texte enthalten also:

  • Fett (**text**), kursiv (*text*), durchgestrichen (~~text~~).
  • Inline-Code (`text`) und abgegrenzte Codeblöcke mit optionaler Sprachangabe.
  • Ungeordnete Listen (-, *, +), geordnete Listen (1.), verschachtelte Listen per Einrückung.
  • Blockzitate (> ).
  • Tabellen (GFM-Pipe-Syntax).
  • Aufgabenlisten (- [x], - [ ]).
  • Horizontale Linien (---).
  • Links ([text](url)) und Bilder (![alt](url)).

Wikilayer-Erweiterungen

Einige Formen werden beim Rendern umgeschrieben.

Kurzverweise

Ein Kurzverweis ist ein Link auf die ID eines Knotens, den der Renderer in eine URL des Wikis umschreibt. Er übersteht eine Änderung von Titel oder Slug, weil die ID gleich bleibt.

Kurzverweise auf Seiten

[text](page:N) wird zur kanonischen URL der Zielseite aufgelöst: /{owner}/{wiki}/{id}-{slug} oder, für eine Seite in einer anderen als der Hauptsprache, /{owner}/{wiki}/{lang}/{id}-{slug}. Slugs können sich beim Umbenennen ändern; die ID ist stabil.

Kurzverweise auf Blöcke

[text](block:N) wird zum Anker #block-N aufgelöst: Auf der eigenen Seite des Blocks ist das ein seiteninterner Link, von jeder anderen Seite aus die URL der Seite des Blocks plus dieser Anker.

Hinweisboxen

Optisch abgesetzte Hinweise, geschrieben als > [!KIND]-Blockzitate in der GitHub-Syntax für Hinweisboxen.

Hinweisarten

Hinweise im GitHub-Stil werden als gestaltete Boxen gerendert. Die erste Zeile des Blockzitats nennt die Art:

> [!NOTE]
> Hinweistext.

Unterstützte Arten: NOTE, TIP, IMPORTANT, WARNING, CAUTION. Jede hat eine eigene Farbe und ein eigenes Symbol.

Karteneinbettungen

Eine [!MAP]-Hinweisbox mit lat, lng in der nächsten Zeile bettet eine interaktive Karte ein. Eine dritte Zeile dient, falls vorhanden, als Beschriftung.

> [!MAP]
> 44.7866, 20.4489
> Belgrad, das Stadtzentrum.

Eingebettete Bilder

Ein Bild wird auf dem Server gespeichert und über seinen /s/-Pfad eingebettet. Dafür gibt es zwei MCP-Tools:

  • upload_image nimmt eine öffentliche http- oder https-Adresse oder eine im Gespräch angehängte Datei entgegen. Der Server ruft das Bild selbst ab, sodass seine Bytes nicht durch den Kontext des Agenten gehen müssen. Das eignet sich für einen Agenten im Browser-Chat, der keine Shell hat.
  • request_upload stellt eine Adresse zur einmaligen Verwendung aus, an die ein Agent mit Shell eine lokale Datei sendet: curl --data-binary @<file> -H 'Content-Type: <mime>' '<upload_url>'.

In beiden Fällen wird das Bild in JPEG umgewandelt, mit einer längsten Seite von höchstens 1600 px, und im Wiki gespeichert. upload_image gibt den Pfad zurück; bei request_upload liefert ihn die POST-Anfrage. Der Pfad wird unverändert direkt in den Text eingefügt: ![Alternativtext](/s/images/…).

Neben dem Text, mit Bildunterschrift

Ein Bild, das allein in einem Absatz steht, nimmt die ganze Textbreite ein. Mit einem Titel steht es rechts neben dem Text wie ein Vorschaubild in einer Enzyklopädie: Der Titel wird zur Bildunterschrift, der Text fließt links daran vorbei, und ein Klick öffnet das vollständige Bild.

![Eine Öllampe und eine Steinschale neben einer offenen Tür](/s/images/… "Das Haus in der Abenddämmerung")

Der Alternativtext beschreibt das Bild für Leser, die es nicht sehen können; die Bildunterschrift sagt, was man daraus mitnehmen soll. Ein hohes Bild oder eines, das eher illustriert als erklärt, passt besser neben den Text. Ein Screenshot oder Diagramm, bei dem die Details wichtig sind, behält die volle Breite.

Auf einem Bildschirm in Smartphone-Breite nimmt das Bild die ganze Breite ein; die mobilen Apps zeigen alle Bilder in voller Breite.

Keine externen Hosts

Ein Bild wird nur aus dem eigenen Speicher des Wikis eingebettet, über seinen /s/-Pfad. Ein Schreibvorgang, der ein Bild auf GitHub, Imgur oder einem anderen Host, eine data:-URI oder eine vollständige URL nennt, wird abgelehnt, und ein Bild von anderswo, das bereits in einem Text steht, erscheint als Link. Externe Bilder gehen mit der Zeit verloren, unterliegen Ratenbegrenzungen und verraten ihrem Host, wer die Seite gelesen hat.

Ohne Objektspeicher gibt es keinen Ausweg

Erscheint weder upload_image noch request_upload in der Tool-Liste, ist auf diesem Server kein Objektspeicher konfiguriert, und die Bildeinbettung ist nicht verfügbar; ein externer Host ist kein Ersatz.