Wiki und öffentliche Dokumentation

Jedes Repository hat ein Wiki: Markdown-Seiten, die als eigenes Git-Repository in Forgejo gespeichert sind. fremforge legt einen optionalen öffentlichen Spiegel darüber: Einmal eingeschaltet, wird derselbe Wiki-Inhalt als anonym lesbare Seiten unter frem.sh/<org>/<repo>/wiki veröffentlicht, teilbar ohne fremforge-Anmeldung.

Die Oberflächen

Dieselbe URL, Routing am Edge abhängig vom Cookie. Angemeldete Mitwirkende sehen weiterhin das native Forgejo-Wiki mit Bearbeiten-Schaltfläche und Verlauf; anonyme Besucher sehen die aufgeräumtere öffentliche Darstellung desselben Inhalts, oder sie werden, wenn das Repository SSO-geschützt ist, zuerst zur Anmeldung an deinen Identitätsanbieter geschickt (siehe SSO-geschützter Zugriff).

Den öffentlichen Spiegel einschalten

Organisationsverwaltung → Öffentliche Doku (in der Seitenleistengruppe Content). Wähle ein Repository aus der Liste und dann in seinem Bereich:

1. Schalte Als Doku-Site veröffentlichen ein.
2. Wähle unter Zugriff: Öffentlich (jeder) oder SSO-geschützt (Anmeldung nötig, siehe unten).
3. (Optional) Füge unter Eigenes CSS ein kleines CSS-Snippet ein, um die Darstellung an deine Marke anzupassen: Farben der Kopfzeile, Schriften, Akzentlinien. Das Textfeld ist auf 8 KB begrenzt, und das Zeichen < wird beim Absenden abgewiesen (das verhindert, dass eine HTML-Injektion per </style> in die gerenderte Seite gelangt; CSS braucht < nicht).
4. Speichere.

Die Doku-Site ist innerhalb weniger Sekunden online. Du kannst jederzeit zurück, indem du Veröffentlichen ausschaltest. Die Route fällt dann auf Forgejos native Darstellung zurück, das heißt, anonyme Besucher sehen, was Forgejo ausgeliefert hätte (eine Anmeldung bei privaten Repositorys, natives Wiki-HTML bei öffentlichen).

SSO-geschützter Zugriff

Doku ist standardmäßig anonym. Für ein Repository, dessen Dokumentation intern sein soll, also für deine Leute lesbar, aber nicht für das offene Internet, setzt du Zugriff auf SSO-geschützt. Leser melden sich dann bei deinem eigenen Identitätsanbieter an und müssen in einer Gruppe sein, die du erlaubst. Zwei Dinge machen das günstig:

• Es wird kein fremforge-Nutzer verbraucht und kein Forgejo-Konto angelegt. Ein Doku-Leser ist nur eine Prüfung von Token und Gruppe gegen deinen IdP; er wird nie Mitglied deiner Organisation. Du kannst interne Doku für dein ganzes Unternehmen öffnen, ohne pro Leser einen Nutzer zu bezahlen.
• Es nutzt die SSO-Verbindungen, die du schon hast. Jeder OIDC-Anbieter, den du für die Anmeldung verbunden hast, steht automatisch auch für den Schutz von Doku bereit; du wählst einen pro Repository.

Einrichtung

Organisationsverwaltung → Öffentliche Doku → Repository wählen, dann unter Zugriff:

1. Setze Zugriff auf SSO-geschützt.
2. Wähle den Identitätsanbieter: eine beliebige OIDC-Verbindung aus deinen SSO-Einstellungen.
3. Trage die Erlaubten Gruppen ein (durch Komma oder Zeilenumbruch getrennt). Ein Leser muss in mindestens einer sein. Das sind dieselben Gruppennamen, die du für die Team-Zuordnung verwendest.
4. Speichere.

Einmalige Einrichtung beim Anbieter

Weil fremforge den Leser direkt anmeldet, muss der OIDC-Client deines IdP eine Redirect-URI erlauben:

https://frem.sh/_app/docs-auth/callback

Füge sie einmal pro Anbieter hinzu (nicht pro Repository). Der Bereich Zugriff zeigt die genaue URI zum Kopieren. Nutze dann die Schaltfläche Anmeldung testen am Repository: Sie führt die echte Anmeldung in einem neuen Tab aus und meldet die Gruppen, die dein IdP zurückgegeben hat, sodass du prüfen kannst, ob die Redirect-URI registriert ist und die Erlaubten Gruppen stimmen. Nach einem erfolgreichen Test erscheint die Markierung ✓ Überprüft. Fehlt die Redirect-URI, zeigt dein Anbieter während des Tests seinen eigenen Fehler „redirect URI mismatch“; behebe ihn dort und teste erneut.

Was Leser sehen

Ein Leser öffnet frem.sh/<org>/<repo>/wiki, wird zur Anmeldung an deinen Identitätsanbieter geschickt (oder nutzt eine bestehende IdP-Sitzung) und landet wieder in der Doku. Die Sitzung hält etwa 45 Minuten und wird dann im Hintergrund erneut bei deinem IdP geprüft. Wer sich anmeldet, aber in keiner erlaubten Gruppe ist, bekommt eine klare Seite „kein Zugriff“ statt der Dokumentation. MFA und deren Stufe entscheidet allein dein IdP; fremforge prüft nur ein gültiges Token und die Gruppenmitgliedschaft.

Einen Anbieter nur für Doku nutzen

Du willst einen Identitätsanbieter, der Doku schützt, aber keinerlei Zugriff auf Git oder Repositorys gewährt, etwa ein breites Verzeichnis „alle Mitarbeitenden“? Füge ihn als normale SSO-Verbindung hinzu, lass aber seine Zuordnungen von Gruppen zu Teams leer. Seine Nutzer können Doku lesen (wenn sie in einer erlaubten Gruppe sind), werden aber keinem Team zugeordnet und zählen daher nicht als zahlende Nutzer und bekommen keinen Repository-Zugriff. Leser, die nur die Doku aufrufen, bekommen nie ein Forgejo-Konto; und meldet sich eine solche Person doch einmal direkt in der Git-Oberfläche an, landet sie in keiner Organisation, und das Konto wird automatisch bereinigt.

Schreiben

Die öffentliche Doku rendert denselben Wiki-Inhalt, den Forgejo speichert. Bearbeite das Wiki wie gewohnt (über den Tab Wiki im Repository, Forgejos Markdown-Editor oder indem du <repo>.wiki.git klonst und Markdown pushst). Eine eigene Oberfläche zum Schreiben gibt es nicht. Was du schreibst, sieht die Öffentlichkeit.

Unterstützte Funktionen:

• GitHub-Flavored Markdown über marked.
• Mermaid-Diagramme. Codeblöcke mit ```mermaid werden im Browser über mermaid.min.js gerendert (~3 MB, vom selben Ursprung unter /static/lib/ ausgeliefert und am Edge unveränderlich gecacht).
• Syntaxhervorhebung für Codeblöcke über Prism (ebenfalls vom selben Ursprung).
• Als PDF drucken. Reines Druck-CSS: Cmd+P / Ctrl+P erzeugt eine saubere Darstellung in A4 / Letter. Keine Abhängigkeit von Headless-Chrome, kein serverseitiges PDF-Rendering.
• Navigation in der Seitenleiste. Gegliedert in Abschnitte, die du mit einer Seite _Sidebar steuerst; siehe Navigation in der Seitenleiste unten. Ohne diese Seite wird das Menü automatisch erzeugt.

(Noch) nicht unterstützt:

• Metadaten oder Front Matter pro Seite
• Kommentare
• Eigene Domains (z. B. docs.acme.com → der öffentliche Spiegel). Verfolge das auf der Roadmap der Plattform.

Navigation in der Seitenleiste

Das Menü links gliedert deine Seiten in Abschnitte. Diese Abschnitte steuerst du aus dem Wiki selbst, indem du eine Seite mit genau dem Namen _Sidebar anlegst, dieselbe Konvention für Sonderseiten, die Forgejo verwendet. Ohne Seite _Sidebar wird das Menü für dich erzeugt (siehe Ohne Seite _Sidebar unten); das Ganze ist also rein optional.

Die Seite _Sidebar ist einfaches Markdown. Eine Überschrift beginnt einen Abschnitt; die Listeneinträge darunter werden die Links dieses Abschnitts, in der Reihenfolge, in der du sie schreibst:

• Eine Zeile ## Heading (jede Ebene #–######) beginnt einen neuen Abschnitt.
• Ein Listeneintrag - [Title](Target) wird ein Link. Title erscheint im Menü; Target ist die Wiki-Seite, auf die er verweist.
• Listeneinträge vor der ersten Überschrift bilden oben eine Gruppe ohne Titel (praktisch für einen einzelnen Link „Home“).

Vorlage

Lege eine Wiki-Seite namens _Sidebar in dieser Form an:

- [Home](Home)

## Getting started
- [Quickstart](Quickstart)
- [Install](Install)

## Core concepts
- [Tenants & orgs](Tenants-and-orgs)
- [Permissions](Permissions)

## Operations
- [Backup & DR](Backup-and-DR)
- [Runbooks](Runbooks)

Ausführliches Beispiel

Angenommen, dein Wiki hat die Seiten Home, Quickstart, Tenants & orgs und Runbooks. Diese _Sidebar:

- [Home](Home)

## Get started
- [Quick start guide](Quickstart)

## Reference
- [Tenants and orgs](Tenants-and-orgs)
- [Operational runbooks](Runbooks)

erzeugt ein Menü mit Home ohne Gruppe ganz oben, dann einem Abschnitt Get started mit „Quick start guide“ und dann einem Abschnitt Reference mit „Tenants and orgs“ und „Operational runbooks“. Die Menübeschriftungen (z. B. „Quick start guide“) sind genau der Text in [...]; sie müssen nicht zum Seitentitel passen.

Linkziele

Das Target in [Title](Target) ist der Name der Wiki-Seite. Forgejo macht in Seiten-URLs aus Leerzeichen Bindestriche, daher wird die Seite Tenants & orgs als Tenants-and-orgs verlinkt. Der Abgleich ist tolerant: Groß-/Kleinschreibung, Leerzeichen und Bindestriche werden vereinheitlicht, sodass Tenants and orgs, tenants-and-orgs und Tenants-and-orgs alle auf dieselbe Seite führen. Zwei Kurzformen funktionieren ebenfalls, wenn dir das lieber ist:

• - [[Tenants-and-orgs]]: Wiki-Link-Form; die Menübeschriftung ist der Seitenname.
• - Tenants-and-orgs: nur der Seitenname; wie oben.

Ohne Seite _Sidebar

Gibt es keine Seite _Sidebar, wird das Menü automatisch erzeugt: Jede Wiki-Seite wird aufgeführt, einige bekannte Titel werden in Abschnitte gruppiert und alles andere steht unter Other. Lege eine Seite _Sidebar an, sobald du Gruppierung, Reihenfolge oder Beschriftungen ausdrücklich steuern willst. Die Seite _Sidebar (und die anderen Forgejo-Sonderseiten _Footer und _Header) erscheinen selbst nie als Einträge im Menü.

Tipp: Eine fehlerhafte _Sidebar (ohne Überschriften oder Listeneinträge) wird ignoriert, und das Menü fällt auf das automatische zurück. Ein Tippfehler kann dir also keine leere Seitenleiste bescheren.

Datenschutz

Der Spiegel ist eine schreibgeschützte Projektion eines bestehenden Wikis. fremforge tut Folgendes nicht:

• Etwas auf Kundenseite speichern außer der Opt-in-Zeile pro Repository und dem optionalen CSS-Snippet.
• IP-Adressen oder Cookies von Besuchern an Forgejo weitergeben. Der Abruf des Spiegels bei Forgejo ist ein serverseitiges fetch() ohne Kennungen des Clients.
• Tracking, Werbung oder JavaScript von Dritten einbauen. Die einzigen Skripte vom selben Ursprung sind mermaid und Prism.

Das serverseitige Rendering nutzt das eingebaute HTML-Escaping von marked v18: Rohes HTML im Wiki-Markdown wird beim Rendern maskiert. Der Mermaid-Codeblock ist die eine Ausnahme, die absichtlich wörtlich erhalten bleibt, damit der Renderer im Browser ihn aufgreifen kann.

Wer was sieht

Dieselbe URL, Verhalten je nach Zielgruppe: Angemeldete Mitwirkende sehen das bearbeitbare Wiki mit Bearbeiten-Schaltfläche und Verlauf, anonyme Besucher und Suchmaschinen sehen die öffentliche Darstellung desselben Inhalts.

Grenzen

Verwandte Themen

• Audit-Log: Die Aktionen tenant.public_docs.toggle, tenant.public_docs.custom_css_updated und tenant.public_docs.access_changed (öffentlich ↔ SSO-geschützt, IdP, erlaubte Gruppen) erfassen jede Änderung.
• Authentifizierungsrichtlinie: Die öffentliche Doku ist von der Authentifizierungsrichtlinie unabhängig. Öffentliche Sichtbarkeit ist ein Opt-in pro Repository, auch in Organisationen mit strenger IP-Allowlist. (Der Spiegel setzt die IP-Allowlist nicht durch; er soll öffentlich lesbar sein.)