Wiki og offentlig dokumentation

Hvert repository har en wiki — markdown-sider, der gemmes som et separat Git-repository i Forgejo. fremforge lægger et valgfrit offentligt mirror ovenpå: slå det til én gang, så udgives det samme wiki-indhold som sider, alle kan læse uden login, på frem.sh/<org>/<repo>/wiki — og kan deles uden et fremforge-login.

Fladerne

Samme URL, routing ved kanten afhængigt af cookies. En samarbejdspartner, der er logget ind, ser stadig Forgejos egen wiki med redigeringsknap og historik; en anonym besøgende ser den renere offentlige visning af det samme indhold — eller bliver, når repositoriet er SSO-beskyttet, sendt til din identitetsudbyder for først at logge ind (se SSO-beskyttet adgang).

Slå det offentlige mirror til

Administration → Offentlig dokumentation (i sidebjælkens gruppe Organisation). Vælg et repository fra listen, og gør så følgende i dets panel:

1. Slå Offentliggør som dokumentationssite til.
2. Vælg Adgang: Offentlig — alle eller SSO-beskyttet (login påkrævet — se nedenfor).
3. (Valgfrit) Indsæt et lille CSS-uddrag i Tilpasset CSS for at give visningen dit eget udtryk — farver i headeren, skrifttyper, accentlinjer. Tekstfeltet er begrænset til 8 KB, og tegnet < afvises, når du gemmer (det forhindrer, at </style>-HTML-injektion slipper ud i den viste side; CSS har ikke reelt brug for <).
4. Gem.

Dokumentationssitet er i luften inden for få sekunder. Du kan til enhver tid fortryde ved at slå Offentliggør fra — ruten falder så tilbage til Forgejos egen visning, hvilket betyder, at anonyme besøgende ser det, Forgejo ville have vist (login for private repositories, Forgejos egen wiki-HTML for offentlige repositories).

SSO-beskyttet adgang

Dokumentation er som standard anonym. For et repository, hvis dokumentation skal være intern — læsbar for dine egne folk, men ikke for hele internettet — sætter du Adgang til SSO-beskyttet. Læserne logger så ind med din egen identitetsudbyder og skal være i en gruppe, du tillader. To ting gør det billigt:

• Der bruges ingen fremforge-bruger, og der oprettes ingen Forgejo-konto. En læser af dokumentationen er blot en kontrol af token + gruppe mod din IdP — vedkommende bliver aldrig medlem af din organisation. Du kan åbne intern dokumentation for hele virksomheden uden at købe en bruger pr. læser.
• Den genbruger de SSO-forbindelser, du allerede har. Enhver OIDC-udbyder, du har forbundet til login, er automatisk tilgængelig til at beskytte dokumentation — vælg én pr. repository.

Opsætning

Administration → Offentlig dokumentation → vælg repositoriet, og gør så følgende under Adgang:

1. Sæt Adgang til SSO-beskyttet.
2. Vælg Identitetsudbyder — en hvilken som helst OIDC-forbindelse fra dine SSO-indstillinger.
3. Angiv de Tilladte grupper (adskilt med komma eller linjeskift). En læser skal være i mindst én af dem. Det er de samme gruppenavne, som du bruger til teamkobling.
4. Gem.

Engangsopsætning hos udbyderen

Fordi fremforge logger læseren ind direkte, skal din IdP’s OIDC-klient tillade én redirect-URI:

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

Tilføj den én gang pr. udbyder (ikke pr. repository). Panelet Adgang viser den præcise URI, der skal kopieres. Brug derefter knappen Test login på repositoriet — den kører det rigtige login i en ny fane og rapporterer de grupper, din IdP returnerede, så du kan bekræfte, at redirect-URI’en er registreret, og at Tilladte grupper er sat rigtigt. Mærket ✓ Verificeret vises, når en test er lykkedes. Mangler redirect-URI’en, viser din udbyder sin egen fejl om “redirect URI mismatch” under testen — ret det der, og test igen.

Hvad læserne ser

En læser åbner frem.sh/<org>/<repo>/wiki, sendes til din identitetsudbyder for at logge ind (eller bruger en eksisterende IdP-session) og lander tilbage i dokumentationen. Sessionen varer omkring 45 minutter og kontrolleres derefter stille igen hos din IdP. En læser, der logger ind, men ikke er i en tilladt gruppe, får en tydelig side om manglende adgang i stedet for dokumentationen. MFA og dets niveau afgøres helt af din IdP — fremforge kontrollerer kun et gyldigt token og gruppemedlemskab.

En udbyder kun til dokumentation

Vil du have en identitetsudbyder, der beskytter dokumentation, men ingen adgang giver til git eller repositories — for eksempel et bredt katalog over “alle medarbejdere”? Tilføj den som en almindelig SSO-forbindelse, men lad dens koblinger mellem grupper og teams være tomme. Dens brugere kan læse dokumentation (når de er i en tilladt gruppe), men kobles ikke til noget team, så de får hverken en bruger eller adgang til repositories. Læsere, der når dokumentationen, får aldrig en Forgejo-konto; og logger sådan en person nogensinde direkte ind i git-brugerfladen, lander vedkommende i ingen organisation, og kontoen ryddes automatisk op.

Redigering

Den offentlige dokumentation viser det samme wiki-indhold, som Forgejo gemmer — redigér wikien på den almindelige måde (fanen Wiki på repositoriet, Forgejos markdown-editor eller ved at klone <repo>.wiki.git og pushe markdown). Der er ingen separat redigeringsflade. Det, du skriver, er det, offentligheden ser.

Understøttede funktioner:

• GitHub-Flavored Markdown via marked.
• Mermaid-diagrammer. ```mermaid-kodeblokke vises på klientsiden via mermaid.min.js (~3 MB, serveret fra samme oprindelse fra /static/lib/, cachet uforanderligt ved kanten).
• Syntaksfremhævning af kodeblokke via Prism (også fra samme oprindelse).
• Udskriv til PDF. Ren print-CSS — Cmd+P / Ctrl+P giver en ren visning i A4 / Letter. Ingen afhængighed af headless Chrome, ingen PDF-generering på serversiden.
• Navigation i sidebjælken. Grupperet i afsnit, du selv styrer med en _Sidebar-side — se Navigation i sidebjælken nedenfor. Uden en sådan side genereres menuen automatisk.

Ikke understøttet (endnu):

• Metadata eller front matter pr. side
• Kommentarer
• Eget domæne (f.eks. docs.acme.com → det offentlige mirror). Følg det på platformens køreplan.

Navigation i sidebjælken

Menuen til venstre grupperer dine sider i afsnit. Du styrer de afsnit fra selve wikien ved at tilføje en side, der hedder præcis _Sidebar — den samme konvention for specielle sider, som Forgejo bruger. Uden en _Sidebar-side genereres menuen for dig (se Uden en _Sidebar-side nedenfor), så det er helt valgfrit.

_Sidebar-siden er almindelig markdown. En overskrift begynder et afsnit; punkterne i listen under den bliver links i det afsnit, i den rækkefølge du skriver dem:

• En linje ## Heading (alle niveauer #–######) begynder et nyt afsnit.
• Et listepunkt - [Title](Target) bliver et link. Title er det, der vises i menuen; Target er den wiki-side, der linkes til.
• Listepunkter skrevet før den første overskrift danner en gruppe uden titel øverst (praktisk til et enkelt “Home”-link).

Skabelon

Opret en wiki-side med navnet _Sidebar i denne form:

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

Gennemgået eksempel

Lad os sige, at din wiki har siderne Home, Quickstart, Tenants & orgs og Runbooks. Denne _Sidebar:

- [Home](Home)

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

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

giver en menu med Home uden gruppe øverst, derefter et afsnit Get started med “Quick start guide” og så et afsnit Reference med “Tenants and orgs” og “Operational runbooks”. Bemærk, at menuens tekster (f.eks. “Quick start guide”) er det, du skriver i [...] — de behøver ikke at svare til sidens titel.

Linkmål

Target i [Title](Target) er navnet på wiki-siden. Forgejo laver mellemrum om til bindestreger i sidernes URL’er, så siden Tenants & orgs linkes som Tenants-and-orgs. Sammenligningen er tilgivende — store og små bogstaver, mellemrum og bindestreger normaliseres — så Tenants and orgs, tenants-and-orgs og Tenants-and-orgs peger alle på samme side. To korte former virker også, hvis du foretrækker dem:

• - [[Tenants-and-orgs]] — wiki-link-form; menuens tekst er sidens navn.
• - Tenants-and-orgs — blot sidens navn; samme som ovenfor.

Uden en _Sidebar-side

Er der ingen _Sidebar-side, genereres menuen automatisk: alle wiki-sider vises, nogle få velkendte titler grupperet i afsnit og alt andet under Other. Tilføj en _Sidebar-side, når du vil have udtrykkelig kontrol over gruppering, rækkefølge eller tekster. _Sidebar-siden (og Forgejos andre specielle sider _Footer og _Header) vises aldrig selv som punkter i menuen.

Tip: en fejlformateret _Sidebar (uden overskrifter eller listepunkter) ignoreres — menuen falder tilbage til den automatiske, så en tastefejl ikke kan efterlade dig med en tom sidebjælke.

Privatliv

Mirroret er en skrivebeskyttet projektion af en eksisterende wiki. fremforge:

• Gemmer intet om kunden ud over rækken for tilvalget pr. repository og det valgfri CSS-uddrag.
• Videresender ikke besøgendes IP-adresser eller cookies til Forgejo. Mirrorets kald til Forgejo er et fetch() på serversiden uden klientidentifikatorer.
• Tilføjer ikke sporing, reklamer eller JavaScript fra tredjeparter. De eneste scripts fra samme oprindelse er mermaid + Prism.

Visningen på serversiden bruger den indbyggede HTML-escaping i marked v18 — rå HTML i wikiens markdown escapes ved visning. Mermaid-kodeblokken er den ene undtagelse, der bevidst bevares uændret, så visningen på klientsiden kan tage den op.

Hvem ser hvad

Samme URL, forskellig opførsel efter publikum: samarbejdspartnere, der er logget ind, ser den redigerbare wiki med redigeringsknap og historik, mens anonyme besøgende og søgemaskiner ser den offentlige visning af det samme indhold.

Grænser

Relateret

• Revisionslog — handlingerne tenant.public_docs.toggle, tenant.public_docs.custom_css_updated og tenant.public_docs.access_changed (offentlig ↔ SSO-beskyttet, IdP, tilladte grupper) registrerer hver ændring.
• Godkendelsespolitik — offentlig dokumentation er uafhængig af godkendelsespolitikken. Offentlig synlighed er et tilvalg pr. repository, også i organisationer med strenge IP-tilladelseslister. (Mirroret håndhæver ikke IP-tilladelseslisten; det er beregnet til at kunne læses offentligt.)