Skip to content

DOC-SETUP.md

Latest commit

 

History

History
98 lines (67 loc) · 2.51 KB

DOC-SETUP.md

File metadata and controls

98 lines (67 loc) · 2.51 KB

Top 👌 ! On a pas mal avancé aujourd’hui. Voici un document clair retraçant les étapes, que tu peux garder comme

📓 Journal de mise en place – Hugo + Hextra + GitHub Pages

1. Création du repo

  • Repo GitHub : Documentation-Template
  • Clone local → dossier 9-Hugo-Hextra/

2. Installation des outils

  • Hugo Extended installé (v0.147.1)
  • Go installé (v1.25.0) pour gérer Hugo Modules

3. Initialisation du site Hugo

hugo new site . --force
hugo mod init github.com/wilonweb/Documentation-Template

4. Ajout du thème Hextra (via Modules)

hugo.toml minimal :

baseURL = "/"
languageCode = "fr"
title = "Ma Doc"
enableRobotsTXT = true
enableGitInfo = true

[module]
  [[module.imports]]
    path = "github.com/imfing/hextra"

[markup]
  [markup.goldmark.renderer]
    unsafe = true
  [markup.highlight]
    style = "github"

Récupération du thème :

hugo mod get github.com/imfing/hextra@latest
hugo mod tidy
hugo mod vendor

5. Création de contenu de test

  • content/docs/_index.md → Documentation
  • content/docs/intro.md → Introduction (exemple avec Mermaid)
  • Sidebar d’Hextra affichée avec succès

6. Problème de doublon "Introduction"

  • Cause : menus.toml généré avec des entrées [[sidebar]] → doublons.
  • Fix : supprimer config/_default/menus.toml → garder la génération automatique depuis content/docs.

7. Automatisations (batch/.sh)

Création d’un dossier batch/ avec scripts :

  • 01-init-site.sh → init Hugo + theme
  • 02-add-docs-sample.sh → ajoute des pages de test
  • 03-add-actions-pages.sh → ajoute workflow Pages
  • 06-tune-site.sh → tuning interactif (apparence, recherche, repoURL, baseURL, sidebar auto, etc.)

8. Déploiement GitHub Pages

Workflow .github/workflows/deploy.yml :

  • Build avec Hugo Extended
  • Force --baseURL "https://<user>.github.io/<repo>/"
  • Déploiement via actions/deploy-pages@v4
  • Pages activées dans Settings → Pages → GitHub Actions

👉 Résultat attendu : https://wilonweb.github.io/Documentation-Template/

📝 Prochaines étapes

  • Nettoyer content/docs/ pour un template clair (intro, installation, usage, FAQ).
  • Ajouter un badge Pages dans le README.
  • Créer un README minimal (présentation + lien vers la doc).
  • Garder ce fichier comme DOCS-SETUP.md (ou DEVLOG.md).

👉 Donc :

  • README.md : simple, concis, orienté utilisateur.
  • DOCS-SETUP.md : journal technique complet (comme ce fichier).