Wiki en openbare documentatie

Elke repository heeft een wiki: markdownpagina’s die als aparte Git-repository binnen Forgejo worden opgeslagen. fremforge legt daar een openbare spiegel die je zelf aanzet bovenop: zet hem één keer aan, en dezelfde wikiinhoud wordt als anoniem leesbare pagina’s gepubliceerd op frem.sh/<org>/<repo>/wiki, te delen zonder fremforge-login.

De oppervlakken

Dezelfde URL, met routering op de edge op basis van cookies. Een aangemelde medewerker ziet nog steeds de eigen wiki van Forgejo met de bewerkknop en de geschiedenis; een anonieme bezoeker ziet de overzichtelijkere openbare weergave van dezelfde inhoud, of wordt, als de repository SSO-beveiligd is, eerst naar je identiteitsprovider gestuurd om aan te melden (zie Toegang via SSO).

De openbare spiegel aanzetten

Organisatiebeheer → Openbare documentatie (onder de groep Content in de zijbalk). Kies een repository uit de lijst en doe dan in het paneel ervan het volgende:

1. Zet Publiceren als documentatiesite aan.
2. Kies bij Toegang: Openbaar — iedereen of SSO-beveiligd (aanmelden vereist, zie hieronder).
3. (Optioneel) Zet een klein CSS-fragment in Aangepaste CSS om de weergave een eigen huisstijl te geven: kleuren van de kop, lettertypen, accentlijnen. Het tekstvak is beperkt tot 8 KB en het teken < wordt bij het versturen geweigerd (dat voorkomt dat een </style>-HTML-injectie in de weergegeven pagina terechtkomt; CSS heeft < niet echt nodig).
4. Sla op.

De documentatiesite is binnen enkele seconden live. Draai het op elk moment terug door Publiceren uit te zetten; de route valt dan terug op de eigen weergave van Forgejo, wat betekent dat anonieme bezoekers zien wat Forgejo zou hebben getoond (aanmelden bij privérepository’s, de eigen wiki-HTML bij openbare repository’s).

Toegang via SSO

Documentatie is standaard anoniem. Voor een repository waarvan de documentatie intern moet zijn, leesbaar voor je eigen mensen maar niet voor het open internet, zet je Toegang op SSO-beveiligd. Lezers melden zich dan aan bij je eigen identiteitsprovider en moeten in een groep zitten die je toestaat. Twee dingen maken dit goedkoop:

• Er wordt geen fremforge-gebruiker verbruikt en geen Forgejo-account aangemaakt. Een lezer van de documentatie is puur een controle van token en groep tegen je IdP: die wordt nooit lid van je organisatie. Je kunt interne documentatie openstellen voor je hele bedrijf zonder per lezer een gebruiker te kopen.
• Het hergebruikt de SSO-koppelingen die je al hebt. Elke OIDC-provider die je voor aanmelden hebt gekoppeld, is automatisch beschikbaar om documentatie af te schermen; kies er per repository een.

Inrichten

Organisatiebeheer → Openbare documentatie → kies de repository, dan onder Toegang:

1. Zet Toegang op SSO-beveiligd.
2. Kies de Identiteitsprovider: elke OIDC-koppeling uit je SSO-instellingen.
3. Noem de Toegestane groepen (gescheiden door komma’s of nieuwe regels). Een lezer moet in minstens één ervan zitten. Het zijn dezelfde groepsnamen die je gebruikt voor de koppeling aan teams.
4. Sla op.

Eenmalige inrichting bij de provider

Omdat fremforge de lezer rechtstreeks aanmeldt, moet de OIDC-client van je IdP één redirect-URI toestaan:

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

Voeg die één keer per provider toe (niet per repository). Het paneel Toegang toont de exacte URI om te kopiëren. Gebruik daarna de knop Inloggen testen bij de repository: die doorloopt de echte aanmelding in een nieuw tabblad en meldt de groepen die je IdP teruggaf, zodat je kunt bevestigen dat de redirect-URI is geregistreerd en Toegestane groepen goed staat. Zodra een test slaagt, verschijnt de badge ✓ Geverifieerd. Ontbreekt de redirect-URI, dan toont je provider tijdens de test zijn eigen foutmelding “redirect URI mismatch”; los het daar op en test opnieuw.

Wat lezers zien

Een lezer opent frem.sh/<org>/<repo>/wiki, wordt naar je identiteitsprovider gestuurd om aan te melden (of gebruikt een bestaande IdP-sessie) en komt terug op de documentatie. De sessie duurt ongeveer 45 minuten en wordt daarna ongemerkt opnieuw bij je IdP gecontroleerd. Een lezer die zich aanmeldt maar niet in een toegestane groep zit, krijgt een duidelijke pagina “geen toegang” in plaats van de documentatie. MFA en het niveau ervan zijn volledig aan je IdP; fremforge controleert alleen een geldig token en het groepslidmaatschap.

Een provider alleen voor documentatie gebruiken

Wil je een identiteitsprovider die documentatie afschermt maar geen enkele toegang tot git of repository’s geeft, bijvoorbeeld een brede directory met “alle medewerkers”? Voeg hem toe als gewone SSO-koppeling, maar laat de koppelingen van groepen aan teams leeg. De gebruikers ervan kunnen documentatie lezen (als ze in een toegestane groep zitten), maar komen in geen enkel team terecht, dus krijgen ze geen gebruiker en geen toegang tot repository’s. Lezers die bij de documentatie komen, krijgen nooit een Forgejo-account; en meldt zo iemand zich ooit rechtstreeks aan in de git-UI, dan komt diegene in geen enkele organisatie terecht en wordt het account automatisch opgeruimd.

Schrijven

De openbare documentatie toont dezelfde wikiinhoud die Forgejo opslaat: bewerk de wiki op de normale manier (het tabblad Wiki van de repository, de markdowneditor van Forgejo, of door <repo>.wiki.git te clonen en markdown te pushen). Er is geen aparte plek om te schrijven. Wat jij schrijft, ziet het publiek.

Ondersteunde functies:

• GitHub-Flavored Markdown via marked.
• Mermaid-diagrammen. Codeblokken ```mermaid worden aan de clientkant weergegeven via mermaid.min.js (~3 MB, vanaf dezelfde origin geleverd uit /static/lib/, onveranderlijk gecachet op de edge).
• Syntaxmarkering voor codeblokken via Prism (ook vanaf dezelfde origin).
• Afdrukken naar pdf. Pure print-CSS: Cmd+P / Ctrl+P levert een nette weergave in A4 / Letter. Geen afhankelijkheid van headless Chrome, geen pdf-weergave aan de serverkant.
• Navigatie in de zijbalk. Gegroepeerd in onderdelen die je zelf bepaalt met een pagina _Sidebar; zie Navigatie in de zijbalk hieronder. Zonder zo’n pagina wordt het menu automatisch gemaakt.

(Nog) niet ondersteund:

• Metadata of front matter per pagina
• Opmerkingen
• Een eigen domein laten verwijzen (bijv. docs.acme.com → de openbare spiegel). Volg dit op de roadmap van het platform.

Navigatie in de zijbalk

Het menu aan de linkerkant groepeert je pagina’s in onderdelen. Die onderdelen bepaal je vanuit de wiki zelf door een pagina toe te voegen die precies _Sidebar heet: dezelfde conventie voor speciale pagina’s die Forgejo gebruikt. Zonder pagina _Sidebar wordt het menu voor je gemaakt (zie Zonder pagina _Sidebar hieronder), dus dit is volledig optioneel.

De pagina _Sidebar is gewone markdown. Een kop begint een onderdeel; de lijstitems eronder worden de links in dat onderdeel, in de volgorde waarin je ze schrijft:

• Een regel ## Heading (elk niveau #–######) begint een nieuw onderdeel.
• Een lijstitem - [Title](Target) wordt een link. Title is wat in het menu staat; Target is de wikipagina waarnaar het linkt.
• Lijstitems die vóór de eerste kop staan, vormen bovenaan een groep zonder titel (handig voor een losse link “Home”).

Sjabloon

Maak een wikipagina met de naam _Sidebar in deze vorm:

- [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)

Uitgewerkt voorbeeld

Stel dat je wiki de pagina’s Home, Quickstart, Tenants & orgs en Runbooks heeft. Deze _Sidebar:

- [Home](Home)

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

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

levert een menu op met Home zonder groep bovenaan, dan een onderdeel Get started met “Quick start guide”, dan een onderdeel Reference met “Tenants and orgs” en “Operational runbooks”. De labels in het menu (bijv. “Quick start guide”) zijn wat je tussen [...] zet; ze hoeven niet overeen te komen met de titel van de pagina.

Linkdoelen

De Target in [Title](Target) is de naam van de wikipagina. Forgejo maakt van spaties streepjes in pagina-URL’s, dus de pagina Tenants & orgs wordt gelinkt als Tenants-and-orgs. Het matchen is vergevingsgezind: hoofdletters, spaties en streepjes worden genormaliseerd, dus Tenants and orgs, tenants-and-orgs en Tenants-and-orgs verwijzen allemaal naar dezelfde pagina. Twee verkorte vormen werken ook, als je die liever gebruikt:

• - [[Tenants-and-orgs]]: wikilinkvorm; het label in het menu is de paginanaam.
• - Tenants-and-orgs: alleen de paginanaam; hetzelfde als hierboven.

Zonder pagina _Sidebar

Is er geen pagina _Sidebar, dan wordt het menu automatisch gemaakt: elke wikipagina wordt getoond, met een paar bekende titels gegroepeerd in onderdelen en al het andere onder Other. Voeg een pagina _Sidebar toe wanneer je zelf wilt bepalen hoe er wordt gegroepeerd, in welke volgorde en met welke labels. De pagina _Sidebar (en de andere speciale pagina’s van Forgejo, _Footer en _Header) verschijnen zelf nooit als item in het menu.

Tip: een misvormde _Sidebar (zonder koppen of lijstitems) wordt genegeerd en het menu valt terug op het automatische, dus een typfout laat je nooit met een lege zijbalk achter.

Privacy

De spiegel is een alleen-lezen projectie van een bestaande wiki. fremforge:

• Slaat aan de klantkant niets op behalve de opt-in-regel per repository + het optionele CSS-fragment.
• Stuurt IP-adressen of cookies van bezoekers niet door naar Forgejo. De rondgang van de spiegel naar Forgejo is een fetch() aan de serverkant zonder clientgegevens.
• Voegt geen tracking, advertenties of JavaScript van derden toe. De enige scripts van dezelfde origin zijn mermaid + Prism.

De weergave aan de serverkant gebruikt de ingebouwde HTML-escaping van marked v18: ruwe HTML in de markdown van de wiki wordt bij de weergave ge-escaped. Het mermaid-codeblok is de enige uitzondering die bewust letterlijk blijft staan, zodat de weergave aan de clientkant het kan oppikken.

Wie wat ziet

Dezelfde URL, gedrag afhankelijk van het publiek: aangemelde medewerkers zien de bewerkbare wiki met de bewerkknop en de geschiedenis, terwijl anonieme bezoekers en zoekmachines de openbare weergave van dezelfde inhoud zien.

Limieten

Gerelateerd

• Auditlog: de acties tenant.public_docs.toggle, tenant.public_docs.custom_css_updated en tenant.public_docs.access_changed (openbaar ↔ SSO-beveiligd, IdP, toegestane groepen) leggen elke wijziging vast.
• Authenticatiebeleid: openbare documentatie staat los van het authenticatiebeleid. Openbare zichtbaarheid is een opt-in per repository, ook in organisaties met een strenge IP-toegestane lijst. (De spiegel dwingt de IP-toegestane lijst niet af; hij is bedoeld om openbaar leesbaar te zijn.)