Wiki och publik dokumentation

Varje repo har en wiki: markdown-sidor som lagras som ett separat Git-repo i Forgejo. fremforge lägger till en valfri publik spegel ovanpå: slå på den en gång så publiceras samma wikiinnehåll som anonymt läsbara sidor på frem.sh/<org>/<repo>/wiki, som kan delas utan inloggning på fremforge.

Ytorna

Samma URL, med routning vid kanten som beror på cookien. En inloggad medarbetare ser fortfarande Forgejos egen wiki med redigeringsknappen och historiken. En anonym besökare ser den renare publika dokumentationsvyn av samma innehåll, eller skickas, när repot är SSO-skyddat, först till din identitetsleverantör för att logga in (se SSO-skyddad åtkomst).

Slå på den publika spegeln

Organisationens administration → Offentlig dokumentation (under sidomenygruppen Innehåll). Välj ett repo i listan och gör sedan följande i dess panel:

1. Slå på Publicera som dokumentationssida.
2. Välj Åtkomst: Offentlig (alla) eller SSO-skyddad (inloggning krävs, se nedan).
3. (Valfritt) Lägg in ett kort CSS-utdrag i Anpassad CSS för att ge vyn din profil: rubrikfärger, typsnitt, accentlinjer. Textfältet rymmer högst 8 KB, och tecknet < avvisas när du sparar (det hindrar att </style>-HTML-injektion läcker in i den renderade sidan; CSS behöver aldrig < på riktigt).
4. Spara.

Dokumentationssidan publiceras inom några sekunder. Du ångrar när som helst genom att slå av Publicera. Routen faller då tillbaka på Forgejos egen rendering, vilket betyder att anonyma besökare ser det Forgejo annars hade visat (inloggning för privata repon, Forgejos egen wiki-HTML för publika repon).

SSO-skyddad åtkomst

Dokumentation är anonym som standard. För ett repo vars dokumentation ska vara intern, läsbar för dina egna medarbetare men inte för hela internet, ställer du Åtkomst på SSO-skyddad. Läsarna loggar då in med din egen identitetsleverantör och måste tillhöra en grupp som du tillåter. Två saker gör det här billigt:

• Ingen fremforge-användare förbrukas och inget Forgejo-konto skapas. En dokumentationsläsare kontrolleras enbart med en token och en gruppkontroll mot din IdP. Läsaren blir aldrig medlem i din organisation. Du kan öppna intern dokumentation för hela företaget utan att köpa en användare per läsare.
• Den återanvänder de SSO-anslutningar du redan har. Varje OIDC-leverantör som du har anslutit för inloggning kan automatiskt användas för att skydda dokumentation. Välj en per repo.

Ställa in det

Organisationens administration → Offentlig dokumentation → välj repot, och gör sedan följande under Åtkomst:

1. Ställ Åtkomst på SSO-skyddad.
2. Välj Identitetsleverantör: vilken OIDC-anslutning som helst från dina SSO-inställningar.
3. Ange Tillåtna grupper (separerade med kommatecken eller radbrytning). En läsare måste tillhöra minst en av dem. Det är samma gruppnamn som du använder för teammappning.
4. Spara.

Engångsinställning hos leverantören

Eftersom fremforge loggar in läsaren direkt måste din IdP:s OIDC-klient tillåta en omdirigerings-URI:

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

Lägg till den en gång per leverantör (inte per repo). Panelen Åtkomst visar exakt vilken URI du ska kopiera. Använd sedan knappen Testa inloggning på repot. Den kör den riktiga inloggningen i en ny flik och visar de grupper som din IdP returnerade, så att du kan bekräfta att omdirigerings-URI:n är registrerad och att Tillåtna grupper är rätt inställt. Märket ✓ Verifierad visas när ett test har lyckats. Om omdirigerings-URI:n saknas visar din leverantör sitt eget felmeddelande om att omdirigerings-URI:n inte stämmer under testet. Rätta det där och testa igen.

Vad läsarna ser

En läsare öppnar frem.sh/<org>/<repo>/wiki, skickas till din identitetsleverantör för att logga in (eller återanvänder en befintlig IdP-session) och kommer tillbaka till dokumentationen. Sessionen varar i ungefär 45 minuter och kontrolleras sedan tyst på nytt mot din IdP. En läsare som loggar in men inte tillhör någon tillåten grupp får en tydlig sida om att åtkomst saknas i stället för dokumentationen. MFA och dess nivå bestäms helt av din IdP; fremforge kontrollerar bara att token är giltig och att läsaren är medlem i gruppen.

Använda en leverantör bara för dokumentation

Vill du ha en identitetsleverantör som skyddar dokumentation men inte ger någon åtkomst till Git eller repon alls, till exempel en bred katalog för all personal? Lägg till den som en vanlig SSO-anslutning, men lämna dess mappningar från grupp till team tomma. Dess användare kan läsa dokumentation (när de tillhör en tillåten grupp) men mappas inte till något team, så de förbrukar ingen användare och får ingen åtkomst till repon. Läsare som når dokumentationen får aldrig något Forgejo-konto, och om en sådan person någon gång loggar in direkt i Git-gränssnittet hamnar hen inte i någon organisation och kontot rensas bort automatiskt.

Skriva innehåll

Den publika dokumentationen renderar samma wikiinnehåll som Forgejo lagrar. Redigera wikin på vanligt sätt (fliken Wiki på repot, Forgejos markdown-redigerare, eller genom att klona <repo>.wiki.git och pusha markdown). Det finns ingen separat yta för att skriva. Det du skriver är det som allmänheten ser.

Det här stöds:

• GitHub-Flavored Markdown via marked.
• Mermaid-diagram. Kodblock med ```mermaid renderas på klientsidan via mermaid.min.js (cirka 3 MB, levereras från samma origin under /static/lib/ och cachas oföränderligt vid kanten).
• Syntaxmarkering för kodblock via Prism (också från samma origin).
• Skriv ut till PDF. Ren utskrifts-CSS: Cmd+P / Ctrl+P ger en ren A4- eller Letter-utskrift. Inget beroende av headless Chrome och ingen PDF-rendering på servern.
• Navigering i sidomenyn. Grupperas i avsnitt som du styr med en _Sidebar-sida, se Navigering i sidomenyn nedan. Utan en sådan sida genereras menyn automatiskt.

Det här stöds inte (ännu):

• Metadata eller front matter per sida
• Kommentarer
• Egen domän (till exempel docs.acme.com → den publika spegeln). Följ det på plattformens färdplan.

Navigering i sidomenyn

Menyn till vänster grupperar dina sidor i avsnitt. Du styr avsnitten från själva wikin genom att lägga till en sida som heter exakt _Sidebar, samma konvention för specialsidor som Forgejo använder. Utan en _Sidebar-sida genereras menyn åt dig (se Utan en _Sidebar-sida nedan), så det här är helt valfritt.

_Sidebar-sidan är vanlig markdown. En rubrik inleder ett avsnitt, och listpunkterna under den blir länkarna i avsnittet, i den ordning du skriver dem:

• En rad med ## Heading (vilken nivå som helst, #–######) inleder ett nytt avsnitt.
• En listpunkt - [Title](Target) blir en länk. Title är det som visas i menyn; Target är den wikisida som den länkar till.
• Listpunkter som skrivs före den första rubriken bildar en grupp utan rubrik högst upp (praktiskt för en ensam länk till “Home”).

Mall

Skapa en wikisida som heter _Sidebar med den här formen:

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

Genomgånget exempel

Anta att din wiki har sidorna Home, Quickstart, Tenants & orgs och Runbooks. Den här _Sidebar:

- [Home](Home)

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

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

ger en meny med Home utan grupp högst upp, sedan avsnittet Get started med “Quick start guide” och därefter avsnittet Reference med “Tenants and orgs” och “Operational runbooks”. Observera att menyetiketterna (till exempel “Quick start guide”) är det du skriver i texten inom [...]. De behöver inte stämma med sidans titel.

Länkmål

Target i [Title](Target) är wikisidans namn. Forgejo gör om mellanslag till bindestreck i sidornas URL:er, så sidan Tenants & orgs länkas som Tenants-and-orgs. Matchningen är förlåtande: versaler, mellanslag och bindestreck normaliseras, så Tenants and orgs, tenants-and-orgs och Tenants-and-orgs leder alla till samma sida. Två kortformer fungerar också om du föredrar dem:

• - [[Tenants-and-orgs]]: wikilänkform; menyetiketten är sidans namn.
• - Tenants-and-orgs: bara sidnamnet; samma som ovan.

Utan en _Sidebar-sida

Om det inte finns någon _Sidebar-sida genereras menyn automatiskt: varje wikisida listas, några välkända titlar grupperas i avsnitt och allt annat hamnar under Other. Lägg till en _Sidebar-sida när du vill styra grupperingen, ordningen eller etiketterna själv. _Sidebar-sidan (och Forgejos andra specialsidor _Footer och _Header) visas aldrig själva som punkter i menyn.

Tips: en felaktig _Sidebar (utan rubriker eller listpunkter) ignoreras och menyn faller tillbaka på den automatiska, så ett stavfel kan inte lämna dig med en tom sidomeny.

Integritet

Spegeln är en skrivskyddad projektion av en befintlig wiki. fremforge gör inte följande:

• Lagrar något om kunden utöver raden för val per repo och det valfria CSS-utdraget.
• Vidarebefordrar besökarnas IP-adresser eller cookies till Forgejo. Spegelns anrop till Forgejo är en fetch() på serversidan utan klientidentifierare.
• Lägger till spårning, annonser eller JavaScript från tredje part. De enda skripten från samma origin är mermaid och Prism.

Renderingen på serversidan använder den inbyggda HTML-escapingen i marked v18: rå HTML i wikins markdown escapas vid renderingen. Kodblocket för mermaid är det enda undantaget, som avsiktligt bevaras ordagrant så att renderaren på klientsidan kan ta hand om det.

Vem ser vad

Samma URL, beteende som beror på målgruppen: inloggade medarbetare ser den redigerbara wikin med redigeringsknappen och historiken, medan anonyma besökare och sökmotorer ser den publika vyn av samma innehåll.

Gränser

Relaterat

• Granskningslogg: åtgärderna tenant.public_docs.toggle, tenant.public_docs.custom_css_updated och tenant.public_docs.access_changed (offentlig ↔ SSO-skyddad, IdP, tillåtna grupper) registrerar varje ändring.
• Autentiseringspolicy: publik dokumentation är oberoende av autentiseringspolicyn. Publik synlighet är ett val per repo även i organisationer med strikta IP-tillåtelselistor. (Spegeln tillämpar inte IP-tillåtelselistan; den är avsedd att vara läsbar för alla.)