Wiki et documentation publique

Chaque dépôt dispose d’un wiki : des pages Markdown stockées dans un dépôt Git distinct au sein de Forgejo. fremforge y ajoute un miroir public facultatif : activez-le une fois, et le même contenu de wiki est publié sous forme de pages lisibles anonymement à l’adresse frem.sh/<org>/<repo>/wiki, que vous pouvez partager sans compte fremforge.

Les surfaces

Même URL, routage selon le cookie en périphérie. Un collaborateur connecté voit toujours le wiki natif de Forgejo, avec le bouton de modification et l’historique ; un visiteur anonyme voit le rendu épuré de la documentation publique pour le même contenu, ou bien, lorsque le dépôt est protégé par SSO, il est d’abord redirigé vers votre fournisseur d’identité pour se connecter (voir Accès protégé par SSO).

Activer le miroir public

Administration de l’organisation → Documentation publique (dans le groupe Contenu de la barre latérale). Choisissez un dépôt dans la liste, puis dans son panneau :

1. Activez Publier comme site de documentation.
2. Choisissez l’Accès : Public — tout le monde ou Protégé par SSO (connexion requise, voir ci-dessous).
3. (Facultatif) Ajoutez un petit extrait CSS dans CSS personnalisé pour personnaliser le rendu : couleurs d’en-tête, polices, filets d’accentuation. Le champ est limité à 8 Ko et le caractère < est refusé à l’envoi (cela empêche une injection HTML </style> de se retrouver dans la page rendue ; le CSS n’a aucun besoin légitime de <).
4. Enregistrez.

Le site de documentation est en ligne en quelques secondes. Vous pouvez revenir en arrière à tout moment en désactivant la publication : la route revient alors au rendu natif de Forgejo, ce qui signifie que les visiteurs anonymes voient ce que Forgejo aurait servi (la page de connexion pour les dépôts privés, le HTML natif du wiki pour les dépôts publics).

Accès protégé par SSO

La documentation est anonyme par défaut. Pour un dépôt dont la documentation doit rester interne, lisible par vos équipes mais pas par l’internet public, réglez l’Accès sur Protégé par SSO. Les lecteurs se connectent alors avec votre propre fournisseur d’identité et doivent appartenir à un groupe que vous autorisez. Deux éléments rendent cette option peu coûteuse :

• Aucun utilisateur fremforge n’est consommé et aucun compte Forgejo n’est créé. Un lecteur de la documentation fait l’objet d’une simple vérification de jeton et de groupe auprès de votre IdP : il ne devient jamais membre de votre organisation. Vous pouvez ouvrir la documentation interne à toute votre entreprise sans acheter un utilisateur par lecteur.
• Les connexions SSO que vous avez déjà sont réutilisées. Tout fournisseur OIDC que vous avez connecté pour la connexion peut automatiquement servir à protéger la documentation : choisissez-en un par dépôt.

Configuration

Administration de l’organisation → Documentation publique → choisissez le dépôt, puis dans Accès :

1. Réglez l’Accès sur Protégé par SSO.
2. Choisissez le Fournisseur d’identité : n’importe quelle connexion OIDC de vos paramètres SSO.
3. Indiquez les Groupes autorisés (séparés par des virgules ou des retours à la ligne). Un lecteur doit appartenir à au moins l’un d’eux. Ce sont les mêmes noms de groupes que ceux utilisés pour la correspondance des équipes.
4. Enregistrez.

Configuration unique du fournisseur

Comme fremforge connecte directement le lecteur, le client OIDC de votre IdP doit autoriser un URI de redirection :

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

Ajoutez-le une fois par fournisseur (et non par dépôt). Le panneau Accès affiche l’URI exact à copier. Utilisez ensuite le bouton Tester la connexion du dépôt : il effectue une vraie connexion dans un nouvel onglet et indique les groupes renvoyés par votre IdP, ce qui vous permet de confirmer que l’URI de redirection est enregistré et de renseigner correctement les Groupes autorisés. Un badge ✓ Vérifié apparaît dès qu’un test réussit. Si l’URI de redirection manque, votre fournisseur affiche sa propre erreur « redirect URI mismatch » pendant le test : corrigez-la de son côté, puis relancez le test.

Ce que voient les lecteurs

Un lecteur ouvre frem.sh/<org>/<repo>/wiki, est redirigé vers votre fournisseur d’identité pour se connecter (ou profite d’une session IdP existante), puis revient sur la documentation. La session dure environ 45 minutes, puis est revérifiée en silence auprès de votre IdP. Un lecteur qui se connecte sans appartenir à un groupe autorisé obtient une page « accès refusé » explicite au lieu de la documentation. L’authentification multifacteur et son niveau relèvent entièrement de votre IdP : fremforge vérifie seulement la validité du jeton et l’appartenance au groupe.

Utiliser un fournisseur uniquement pour la documentation

Vous voulez un fournisseur d’identité qui protège la documentation sans donner aucun accès Git ni aux dépôts, par exemple un annuaire « tout le personnel » ? Ajoutez-le comme une connexion SSO normale, mais laissez vides ses correspondances groupe→équipe. Ses utilisateurs peuvent lire la documentation (s’ils sont dans un groupe autorisé) sans correspondre à aucune équipe : ils ne consomment donc aucun utilisateur payant et n’ont accès à aucun dépôt. Les lecteurs qui accèdent à la documentation n’obtiennent jamais de compte Forgejo ; et si une telle personne se connecte un jour directement à l’interface Git, elle n’arrive dans aucune organisation et le compte est nettoyé automatiquement.

Rédaction

La documentation publique affiche le même contenu de wiki que celui stocké par Forgejo : modifiez le wiki de la manière habituelle (l’onglet Wiki du dépôt, l’éditeur Markdown de Forgejo, ou en clonant <repo>.wiki.git et en poussant du Markdown). Il n’existe pas d’interface de rédaction séparée. Ce que vous écrivez est ce que voit le public.

Fonctionnalités prises en charge :

• GitHub-Flavored Markdown via marked.
• Diagrammes Mermaid. Les blocs de code ```mermaid sont rendus côté client par mermaid.min.js (~3 Mo, servi depuis la même origine sous /static/lib/, mis en cache de façon immuable en périphérie).
• Coloration syntaxique des blocs de code via Prism (également servi depuis la même origine).
• Impression en PDF. Du CSS d’impression pur : Cmd+P / Ctrl+P produit un rendu A4 / Letter propre. Aucune dépendance à un Chrome sans interface, aucun rendu PDF côté serveur.
• Navigation latérale. Regroupée en sections que vous définissez avec une page _Sidebar, voir Navigation latérale ci-dessous. Sans cette page, le menu est généré automatiquement.

Pas encore pris en charge :

• Métadonnées ou front matter par page
• Commentaires
• Domaine personnalisé (par exemple docs.acme.com → le miroir public). Suivez ce point dans la feuille de route de la plateforme.

Navigation latérale

Le menu de gauche regroupe vos pages en sections. Vous définissez ces sections depuis le wiki lui-même en ajoutant une page nommée exactement _Sidebar, selon la même convention de page spéciale que Forgejo. Sans page _Sidebar, le menu est généré pour vous (voir Sans page _Sidebar ci-dessous) : tout cela est donc entièrement facultatif.

La page _Sidebar est du Markdown simple. Un titre ouvre une section ; les éléments de liste qui le suivent deviennent les liens de cette section, dans l’ordre où vous les écrivez :

• Une ligne ## Titre (n’importe quel niveau de # à ######) ouvre une nouvelle section.
• Un élément de liste - [Title](Target) devient un lien. Title est ce qui s’affiche dans le menu ; Target est la page du wiki vers laquelle il pointe.
• Les éléments de liste écrits avant le premier titre forment un groupe sans titre en haut du menu (pratique pour un lien « Home » isolé).

Modèle

Créez une page de wiki nommée _Sidebar avec cette structure :

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

Exemple détaillé

Supposons que votre wiki contienne les pages Home, Quickstart, Tenants & orgs et Runbooks. Cette page _Sidebar :

- [Home](Home)

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

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

produit un menu avec Home hors groupe en haut, puis une section Get started contenant « Quick start guide », puis une section Reference contenant « Tenants and orgs » et « Operational runbooks ». Notez que les libellés du menu (par exemple « Quick start guide ») correspondent au texte placé entre [...] : ils n’ont pas besoin d’être identiques au titre de la page.

Cibles des liens

La Target de [Title](Target) est le nom de la page du wiki. Forgejo remplace les espaces par des tirets dans les URL des pages : la page Tenants & orgs se lie donc sous la forme Tenants-and-orgs. La correspondance est tolérante (la casse, les espaces et les tirets sont normalisés) : Tenants and orgs, tenants-and-orgs et Tenants-and-orgs mènent tous à la même page. Deux formes abrégées fonctionnent aussi si vous les préférez :

• - [[Tenants-and-orgs]] : forme de lien wiki ; le libellé du menu est le nom de la page.
• - Tenants-and-orgs : nom de page seul ; même résultat que ci-dessus.

Sans page _Sidebar

S’il n’y a pas de page _Sidebar, le menu est généré automatiquement : toutes les pages du wiki sont listées, quelques titres bien connus sont regroupés en sections et tout le reste se trouve sous Other. Ajoutez une page _Sidebar dès que vous voulez maîtriser explicitement le regroupement, l’ordre ou les libellés. La page _Sidebar (ainsi que les autres pages spéciales de Forgejo, _Footer et _Header) n’apparaît jamais elle-même comme élément du menu.

Astuce : une page _Sidebar mal formée (sans titres ni éléments de liste) est ignorée : le menu revient au menu automatique, si bien qu’une faute de frappe ne peut pas vous laisser avec une barre latérale vide.

Confidentialité

Le miroir est une projection en lecture seule d’un wiki existant. fremforge :

• Ne stocke rien côté client au-delà de la ligne d’activation par dépôt et de l’extrait CSS facultatif.
• Ne transmet ni les adresses IP ni les cookies des visiteurs à Forgejo. L’aller-retour du miroir vers Forgejo est un fetch() côté serveur sans aucun identifiant client.
• N’ajoute ni suivi, ni publicité, ni JavaScript tiers. Les seuls scripts servis depuis la même origine sont mermaid et Prism.

Le rendu côté serveur utilise l’échappement HTML intégré de marked v18 : le HTML brut présent dans le Markdown du wiki est échappé au rendu. Le bloc de code mermaid est la seule exception, volontairement conservée telle quelle pour que le moteur de rendu côté client puisse la traiter.

Qui voit quoi

Même URL, comportement selon le public : les collaborateurs connectés voient le wiki modifiable, avec le bouton de modification et l’historique, tandis que les visiteurs anonymes et les moteurs de recherche voient le rendu public du même contenu.

Limites

Voir aussi

• Journal d’audit : les actions tenant.public_docs.toggle, tenant.public_docs.custom_css_updated et tenant.public_docs.access_changed (public ↔ protégé par SSO, IdP, groupes autorisés) tracent chaque modification.
• Politique d’authentification : la documentation publique est indépendante de la politique d’authentification. La visibilité publique s’active dépôt par dépôt, même dans les organisations dotées de listes d’adresses IP autorisées strictes. (Le miroir n’applique pas la liste d’adresses IP autorisées : il est conçu pour être lisible publiquement.)