Wiki og offentlig dokumentasjon

Hvert repository har en wiki: Markdown-sider lagret som et eget Git-repository i Forgejo. fremforge legger et valgfritt offentlig speil oppå: slå det på én gang, så publiseres det samme wikiinnholdet som sider alle kan lese uten innlogging, på frem.sh/<org>/<repo>/wiki, og kan deles uten fremforge-innlogging.

Flatene

Samme URL, ruting i kanten avhengig av informasjonskapsel. En innlogget samarbeidspartner ser fortsatt Forgejos egen wiki med redigeringsknapp og historikk; en besøkende uten innlogging ser den ryddigere offentlige visningen av det samme innholdet, eller, når repositoryet er bak SSO, blir sendt til identitetsleverandøren din for å logge inn først (se Tilgang bak SSO).

Slå på det offentlige speilet

Organisasjonsadministrasjon → Offentlig dokumentasjon (under gruppen Innhold i sidemenyen). Velg et repository fra listen, og deretter i panelet:

1. Slå på Publiser som dokumentasjonsnettsted.
2. Velg Tilgang: Offentlig (alle) eller SSO-beskyttet (krever innlogging; se nedenfor).
3. (Valgfritt) Legg inn et lite CSS-utdrag i Egendefinert CSS for å sette ditt preg på visningen: farger i toppteksten, valg av skrift, aksentlinjer. Tekstfeltet har et tak på 8 KB, og tegnet < avvises ved innsending (hindrer at </style>-HTML-injeksjon lekker inn i den viste siden; CSS trenger ikke < til noe legitimt).
4. Lagre.

Dokumentasjonsnettstedet er oppe i løpet av noen sekunder. Du kan når som helst gå tilbake ved å slå av Publish: ruten faller da tilbake til Forgejos egen visning, som betyr at besøkende uten innlogging ser det Forgejo ellers ville vist (innlogging for private repositoryer, Forgejos egen wiki-HTML for offentlige repositoryer).

Tilgang bak SSO

Dokumentasjonen er åpen uten innlogging som standard. For et repository der dokumentasjonen skal være intern, lesbar for dine folk, men ikke for hele internett, setter du Access til SSO-gated. Leserne logger da inn med din egen identitetsleverandør og må være i en gruppe du tillater. To ting gjør dette billig:

• Ingen fremforge-bruker brukes, og ingen Forgejo-konto opprettes. En leser av dokumentasjonen er bare en kontroll av token og gruppe mot IdP-en din; de blir aldri medlem av organisasjonen din. Du kan åpne intern dokumentasjon for hele selskapet uten å kjøpe en bruker per leser.
• Den gjenbruker SSO-tilkoblingene du allerede har. Enhver OIDC-leverandør du har koblet til for innlogging, er automatisk tilgjengelig for å beskytte dokumentasjon; velg én per repository.

Sette det opp

Organisasjonsadministrasjon → Offentlig dokumentasjon → velg repositoryet, og deretter i Tilgang:

1. Sett Tilgang til SSO-beskyttet.
2. Velg Identitetsleverandør: en hvilken som helst OIDC-tilkobling fra SSO-innstillingene dine.
3. List opp Tillatte grupper (skilt med komma eller linjeskift). En leser må være i minst én av dem. Dette er de samme gruppenavnene du bruker for koblingen til team.
4. Lagre.

Engangsoppsett hos leverandøren

Fordi fremforge logger inn leseren direkte, må OIDC-klienten i IdP-en din tillate én omdirigerings-URI:

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

Legg den til én gang per leverandør (ikke per repository). Access-panelet viser den nøyaktige URI-en du skal kopiere. Bruk deretter knappen Test sign-in på repositoryet: den kjører den ekte innloggingen i en ny fane og rapporterer gruppene IdP-en returnerte, så du kan bekrefte at omdirigerings-URI-en er registrert og sette Allowed groups riktig. Merket ✓ Verified vises når en test lykkes. Hvis omdirigerings-URI-en mangler, viser leverandøren sin egen feilmelding om at omdirigerings-URI-en ikke stemmer, under testen; rett det der og test på nytt.

Hva leserne ser

En leser åpner frem.sh/<org>/<repo>/wiki, sendes til identitetsleverandøren din for å logge inn (eller bruker en eksisterende IdP-sesjon) og havner tilbake på dokumentasjonen. Sesjonen varer i omtrent 45 minutter og sjekker deretter stille på nytt med IdP-en din. En leser som logger inn, men ikke er i en tillatt gruppe, får en tydelig side om at tilgang mangler, i stedet for dokumentasjonen. MFA og nivået på den bestemmes helt av IdP-en din; fremforge kontrollerer bare et gyldig token og gruppemedlemskap.

Bruke en leverandør bare for dokumentasjon

Vil du ha en identitetsleverandør som beskytter dokumentasjon, men ikke gir noen tilgang til git eller repositoryer i det hele tatt, for eksempel en bred katalog over alle ansatte? Legg den til som en vanlig SSO-tilkobling, men la koblingene fra grupper til team stå tomme. Brukerne kan lese dokumentasjon (når de er i en tillatt gruppe), men kobles ikke til noe team, så de får ingen bruker og ingen tilgang til repositoryer. Lesere som når dokumentasjonen, får aldri en Forgejo-konto i det hele tatt; og hvis en slik person noen gang logger inn direkte i git-grensesnittet, havner de ikke i noen organisasjon, og kontoen ryddes bort automatisk.

Skrive innhold

Den offentlige dokumentasjonen viser det samme wikiinnholdet som Forgejo lagrer: rediger wikien på vanlig måte (fanen Wiki i repositoryet, Forgejos Markdown-editor, eller ved å klone <repo>.wiki.git og pushe Markdown). Det finnes ingen egen flate for å skrive. Det du skriver, er det offentligheten ser.

Støttede funksjoner:

• GitHub-Flavored Markdown via marked.
• Mermaid-diagrammer. ```mermaid-kodeblokker vises på klientsiden via mermaid.min.js (~3 MB, levert fra samme origin under /static/lib/, bufret som uforanderlig i kanten).
• Syntaksutheving for kodeblokker via Prism (også fra samme origin).
• Utskrift til PDF. Ren utskrifts-CSS: Cmd+P / Ctrl+P gir en ren A4- eller Letter-utskrift. Ingen avhengighet til headless Chrome, ingen PDF-generering på serveren.
• Navigasjon i sidemenyen. Gruppert i seksjoner du styrer med en _Sidebar-side; se Navigasjon i sidemenyen nedenfor. Uten en slik side genereres menyen automatisk.

Ikke støttet (ennå):

• Metadata eller front matter per side
• Kommentarer
• Egendefinert domene (for eksempel docs.acme.com → det offentlige speilet). Følg med på dette i plattformens veikart.

Navigasjon i sidemenyen

Menyen til venstre grupperer sidene dine i seksjoner. Du styrer seksjonene fra selve wikien ved å legge til en side som heter nøyaktig _Sidebar, den samme konvensjonen for spesialsider som Forgejo bruker. Uten en _Sidebar-side genereres menyen for deg (se Uten en _Sidebar-side nedenfor), så dette er helt valgfritt.

_Sidebar-siden er vanlig Markdown. En overskrift starter en seksjon; listepunktene under den blir lenkene i den seksjonen, i den rekkefølgen du skriver dem:

• En ## Heading-linje (hvilket som helst nivå #–######) starter en ny seksjon.
• Et listepunkt - [Title](Target) blir en lenke. Title er det som vises i menyen; Target er wikisiden det lenkes til.
• Listepunkter skrevet før den første overskriften utgjør en gruppe uten tittel øverst (praktisk for en enslig «Home»-lenke).

Mal

Opprett en wikiside som heter _Sidebar, med denne 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)

Gjennomgått eksempel

La oss si at wikien din har sidene 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)

gir en meny med Home uten gruppe øverst, deretter en seksjon Kom i gang med «Quick start guide», og deretter en seksjon Referanse med «Tenants and orgs» og «Operational runbooks». Legg merke til at menyetikettene (for eksempel «Quick start guide») er det du skriver i [...]-teksten; de trenger ikke stemme med sidetittelen.

Lenkemål

Target i [Title](Target) er navnet på wikisiden. Forgejo gjør mellomrom om til bindestreker i side-URL-er, så siden Tenants & orgs lenkes som Tenants-and-orgs. Matchingen er tilgivende: store og små bokstaver, mellomrom og bindestreker normaliseres, så Tenants and orgs, tenants-and-orgs og Tenants-and-orgs peker alle til samme side. To kortformer virker også hvis du foretrekker dem:

• - [[Tenants-and-orgs]]: wikilenkeform; menyetiketten er sidenavnet.
• - Tenants-and-orgs: bare sidenavnet; samme som over.

Uten en _Sidebar-side

Hvis det ikke finnes noen _Sidebar-side, genereres menyen automatisk: hver wikiside listes, med noen få velkjente titler gruppert i seksjoner og alt annet under Annet. Legg til en _Sidebar-side når du vil ha uttrykkelig kontroll over gruppering, rekkefølge eller etiketter. _Sidebar-siden (og Forgejos andre spesialsider, _Footer og _Header) vises aldri som punkter i selve menyen.

Tips: en feilformet _Sidebar (uten overskrifter eller listepunkter) ignoreres, og menyen faller tilbake til den automatiske, så en skrivefeil kan ikke gi deg en tom sidemeny.

Personvern

Speilet er en skrivebeskyttet projeksjon av en eksisterende wiki. fremforge gjør ikke følgende:

• Lagrer noe på kundesiden utover raden for tilvalget per repository og det valgfrie CSS-utdraget.
• Videresender IP-adresser eller informasjonskapsler fra besøkende til Forgejo. Speilets rundtur til Forgejo er en fetch() på serveren uten klientidentifikatorer.
• Legger til sporing, reklame eller JavaScript fra tredjeparter. De eneste skriptene, fra samme origin, er mermaid og Prism.

Visningen på serveren bruker den innebygde HTML-escapingen i marked v18: rå HTML i wiki-Markdownen escapes ved visning. Mermaid-kodeblokken er det ene unntaket som bevisst bevares ordrett, slik at visningen på klientsiden kan plukke den opp.

Hvem som ser hva

Samme URL, oppførsel avhengig av målgruppe: innloggede samarbeidspartnere ser den redigerbare wikien med redigeringsknapp og historikk, mens besøkende uten innlogging og søkemotorer ser den offentlige visningen av det samme innholdet.

Begrensninger

Relatert

• Revisjonslogg: handlingene tenant.public_docs.toggle, tenant.public_docs.custom_css_updated og tenant.public_docs.access_changed (offentlig ↔ bak SSO, IdP, tillatte grupper) sporer hver endring.
• Autentiseringspolicy: den offentlige dokumentasjonen er uavhengig av autentiseringspolicyen. Offentlig synlighet er et tilvalg per repository, selv i organisasjoner med strenge IP-tillatelseslister. (Speilet håndhever ikke IP-tillatelseslisten; det er ment å være offentlig lesbart.)