Source Viewer Plugin

Source Viewer zeigt Quelldateien im Wiki an, ohne sie zu kopieren: Syntaxhervorhebung, Zeilennummern, Zeilenanker und Dauerverweise, wahlweise als Block auf der Seite oder in einer Schublade. Woher die Datei stammt, entscheidet ein Anbieter — lokal und Medienordner sind eingebaut, Git und ADO-gehostetes Git kommen aus den zugehörigen Paketen. Gedacht ist es für Autoren, die Code auf einer Seite zeigen, und für Leser, die ihn im Zusammenhang lesen.

Erste Schritte

Schnelleinstieg: Eine Quelltextdatei auf einer Seite anzeigen — der kürzeste Weg zum ersten Ergebnis, in drei Schritten.

Anbieter wählen → Marke setzen → Darstellung prüfen

Häufige Aufgaben

Was Sie wollen	Für wen	Wo Sie das tun	Anleitung
eine Datei auf einer Seite zeigen	Autor	Marke `{{source>…}}`	Beide Schreibweisen
nur einen Zeilenbereich zeigen	Autor	Marke mit Zeilenangabe	Beide Schreibweisen
auf eine einzelne Zeile verweisen	Autor	Zeilenanker	Der Dokumentenkopf
eine Datei aus einem Git-Repository zeigen	Autor	–	wkdogit
eine Datei aus Azure DevOps zeigen	Autor	–	ADO-Git
eine Markdown-Datei als Dokument darstellen	Autor	–	Markdown als Dokument
Größen- und Typgrenzen einstellen	Verwaltung	Konfigurationsmanager	Konfiguration

Zweck

Zeigt Quelldateien im Wiki an, ohne sie zu kopieren: Syntaxhervorhebung, Zeilennummern, Zeilenanker und Permalinks, dazu eine Schublade für die Ansicht ohne Seitenwechsel. Woher die Datei kommt, entscheidet ein Anbieter — das Plugin selbst kennt weder git noch ADO.

Angemeldeter Dienst (siehe Core Plugin): source.providers.

Beide Schreibweisen

Gleichwertig, gleiches Ergebnis (siehe Core Plugin):

{{source>ado:wk:DokuWiki-Plugins:mein-repo:master:README.md}}

<wk:source ref="ado:wk:DokuWiki-Plugins:mein-repo:master:README.md"
             title="Plugin-README"
             subtitle="Einstiegsdokument · Stand master"
             badges="language"
             actions="permalink,drawer" />

In der DokuWiki-Form stehen weitere Angaben hinter Pipes: {{source>spec|mode=drawer|numbers=0}}.

Angabe	Wirkung
`mode`	`inline` / `block` / `preview` / `drawer`
`numbers`	Zeilennummern an/aus
`lang`	Sprache für die Hervorhebung erzwingen
`title`	Anzeigename im Kopf statt des abgeleiteten Dateinamens
`subtitle`	Zusatzzeile hinter dem Namen; ersetzt die Vollangabe
`badges`	Auswahl der Abzeichen: `ref`, `language`, `status`
`actions`	Auswahl der Aktionen: `view`, `permalink`, `raw`, `download`, `drawer`, `refresh`

badges und actions unterscheiden drei Zustände: Angabe fehlt = alles zeigen, badges=„“ = nichts zeigen, Liste = genau diese. Die Reihenfolge kommt nicht aus der Seite — die Abfolge im Kopf gehört zur Komponente, damit zwei Einbettungen mit gleicher Auswahl auch gleich aussehen.

Zeilenbereich: ein Anker am Ende der Angabe klammert den gezeigten Ausschnitt, z. B. …/App.php#L10-L20.

Anbieter

Präfix	Quelle	Von
`page:`	Wiki-Seite	dieses Plugin
`media:`	Medienarchiv	dieses Plugin
`git:`	lokales Repository	Git Plugin
`ado:`	Azure-DevOps-Repository	wkdoadogit

Jeder Anbieter prüft die DokuWiki-ACL vor dem Lesen. Eine Datei ohne Leserecht liefert die ACL-Meldung, nicht den Inhalt — und auch keinen Hinweis darauf, dass sie existiert.

Der Dokumentenkopf

Der Kopf über jeder Einbettung ist nicht von diesem Plugin gestaltet, sondern die geteilte Komponente aus wkfluentui. Das Plugin beschreibt nur, was darin steht; Anordnung, Kürzung, Tönung und der oben verankerte Balken werden zentral entschieden — damit eine Quelldatei und der Repo-Browser auf derselben Seite dieselbe Sprache sprechen.

Ohne Designsystem zeichnet das Plugin einen bewusst schlichten Ersatzkopf mit demselben Inhalt.

Markdown als Dokument

Ist render_markdown eingeschaltet, werden .md-Dateien formatiert dargestellt statt hervorgehoben — mit DokuWikis eigenem Parser, der GitHub-Markdown mitbringt. Der Kopf bietet dann zusätzlich Als Quelltext bzw. Als Dokument an.

Ausgeschaltet voreingestellt, und das ist eine Sicherheitsentscheidung. Der Wiki-Parser führt jedes registrierte Syntax-Plugin aus. Eine so gerenderte Datei bekommt damit dieselbe Reichweite wie eine Wiki-Seite: eine Einbettung oder ein Plugin-Tag in einer README läuft, statt gezeigt zu werden. Wer über einen git-Proxy schreiben darf, ist womöglich ein weiterer Kreis als die Editoren des Wikis — und erhielte damit Autorenrechte im Wiki.

Nur dort einschalten, wo die Quellen hinter den Anbietern so vertrauenswürdig sind wie das Wiki selbst. Zeilenbereiche und der Vorschaumodus bleiben auch dann Quelltext.

Beim Rendern fremder Inhalte werden die Abschnitt-Bearbeiten-Marker entfernt. Der Wiki-Renderer schreibt zu jeder Überschrift einen Marker mit Byte-Bereich; diese Bereiche stammen aus der eingebetteten Datei, würden aber als Bereiche der Wiki-Seite gelesen. Ein Klick auf einen solchen Knopf überschreibt sonst beliebige Bytes der Seite.

Konfiguration

Einstellung	Vorgabe	Bedeutung
`cache`	`1`	hervorgehobene Einbettungen zwischenspeichern (verfällt mit der Quelle)
`max_bytes`	`262144`	256 KB Obergrenze → Status toolarge
`max_lines`	`1000`	Zeilenobergrenze; darüber gekürzt und gekennzeichnet
`preview_lines`	`12`	Zeilen im Vorschaumodus
`highlight`	`1`	Hauptschalter der Hervorhebung
`default_mode`	`block`	Modus, wenn die Einbettung keinen nennt
`default_numbers`	`1`	Zeilennummern, wenn die Einbettung nichts sagt
`render_markdown`	`0`	siehe oben

Die Obergrenzen sind zugleich eine Lastbremse: die Hervorhebung kostet Rechenzeit proportional zur Dateigröße.

local_roots gibt es nicht. Frühere Fassungen dieser Seite führten den Schlüssel in der Tabelle oben, als reserviert für einen künftigen local:-Anbieter. Über das Merkmal war das richtig, über den Schlüssel nicht: er ist nirgends deklariert und wird von keiner Zeile Code gelesen. Die Tabelle sagt genau eines aus — was der Konfigurationsmanager zeigt —, und dazu gehörte er nie. Kommt der Anbieter, kommt der Schlüssel mit ihm.

Grenzen

Die Schublade lädt über ?call=wksourceview_view; der Endpunkt prüft Sicherheitstoken und ACL erneut, serverseitig.
Nur die erste Einbettung einer Seite wandert in den Werkzeugleisten-Platz der Schale. Ein Balken ganz oben, der stillschweigend nur eine von fünf Quellen steuert, wäre schlechter als keiner.

Paketangaben

Plugin: wksourceview
Namespace: lib/plugins/wksourceview/
Autor: Wolfgang van der Stille Wolfgang.van.der.Stille@gmail.com (The White Knight Labs)
Lizenz: GPL 2.0-only