demo-pages-mkdocs

Démo de Forgejo Pages avec MkDocs Material, build automatique via Forgejo Actions.

👉 Voir le site en ligne : https://gt-forgejo.pages.incubateur.education-nationale.eu/demo-pages-mkdocs/

C'est quoi ?

Un dépôt minimal qui prouve que le pipeline Forgejo Pages fonctionne de bout en bout :

1. Vous éditez vos fichiers Markdown dans docs/
2. Vous poussez sur main
3. Un workflow Forgejo Actions build le site avec MkDocs et publie via actions/git-pages@v2
4. Le site est en ligne en ~1 minute, sans aucun secret ni token à configurer

C'est exactement le fonctionnement de GitHub Pages / GitLab Pages.

Refaire la même chose pour mon projet (3 minutes)

1. Forker ce dépôt

Bouton Forker en haut à droite de https://forgejo.incubateur.education-nationale.eu/gt-forgejo/demo-pages-mkdocs

Ou en ligne de commande :

git clone https://forgejo.incubateur.education-nationale.eu/gt-forgejo/demo-pages-mkdocs.git
cd demo-pages-mkdocs

2. Modifier le contenu

Tout est dans docs/ en Markdown :

• docs/index.md — la page d'accueil
• docs/utilisation.md — un exemple de page secondaire

Pour ajouter une page, créez docs/ma-page.md et déclarez-la dans mkdocs.yml (section nav:).

3. Pousser

git add .
git commit -m "Mon premier site"
git push

Onglet Actions du dépôt → regardez le workflow tourner (~1 minute). Une fois en vert, le site est en ligne sur :

https://<votre-org>.pages.incubateur.education-nationale.eu/<votre-repo>/

Pas de secret, pas de mot de passe

L'action actions/git-pages@v2 utilise automatiquement le GITEA_TOKEN injecté par Forgejo dans le workflow. Le serveur git-pages le revérifie auprès de Forgejo pour confirmer que vous avez bien le droit de publier sur ce sous-domaine. Rien à configurer côté repo.

Si ça ne marche pas

• Le workflow échoue : cliquer dessus pour voir le log. Le plus souvent une erreur dans un fichier Markdown.
• Le site reste en 404 : attendre 60 secondes (cache), puis rafraîchir.
• Le site est moche : c'est le thème par défaut MkDocs Material. Voir la doc Material pour personnaliser.

Toute autre question : gt-forgejo/documentation ou incubateur@education.gouv.fr.

Pour les curieux

Documentation technique :

• docs/PAGES.md — guide utilisateur Forgejo Pages
• docs/adr/014-pages-git-pages-transparent.md — choix d'architecture

Stack : Forgejo Actions → actions/git-pages@v2 → git-pages (codeberg.org/git-pages) → bucket S3 → Caddy + TLS wildcard.