Antora : créez vos sites docs statiques

Antora est un générateur de sites de documentation statiques qui lit des fichiers AsciiDoc directement dans des dépôts Git, puis produit un site HTML que n'importe quel serveur web peut servir. Cette leçon facultative s'adresse à qui doit documenter plusieurs projets ou plusieurs versions d'un logiciel dans un seul site : vous y installez Antora, vous structurez un dépôt de documentation, vous gérez les versions, vous habillez le site et vous le déployez.

Elle suppose que vous savez utiliser Git et un terminal, et que vous avez déjà vu la syntaxe d'AsciiDoc (voir la leçon AsciiDoc). Pour un site de documentation plus classique, rédigé en Markdown, le fil rouge de ce module reste Astro Starlight : Antora prend l'avantage quand la documentation vit dans plusieurs dépôts ou doit exister en plusieurs versions.

Ce que vous allez apprendre

Au terme de cette leçon, vous saurez :

• expliquer ce qu'apporte Antora par rapport à un simple générateur de site statique ;
• distinguer composant, module, page et playbook ;
• installer Antora et générer un premier site à partir d'un playbook ;
• versionner la documentation avec les branches Git ;
• personnaliser l'apparence du site avec un bundle d'interface ;
• déployer le site sur un serveur web, GitHub Pages ou Netlify, puis l'automatiser avec GitHub Actions.

Historique

Antora est développé par la société OpenDevise, dont l'équipe maintient aussi Asciidoctor, le convertisseur de référence d'AsciiDoc. L'idée de départ : traiter la documentation comme du code, en la laissant dans les dépôts Git des projets plutôt que de la copier dans un outil à part, et assembler un seul site à partir de plusieurs dépôts et de plusieurs branches.

Le projet est open source, publié sous licence MPL-2.0 et hébergé sur GitLab (gitlab.com/antora/antora). D'après le registre npm du paquet @antora/cli, la version 1.0.0 date d'avril 2018, la 2.0.0 de décembre 2018 et la 3.0.0 de décembre 2021 ; la dernière version publiée au 2026-10-13 est la 3.2.1. Antora est écrit en JavaScript et s'exécute avec Node.js, d'où son installation par npm.

Fonctionnalités principales

Antora est riche en fonctionnalités qui facilitent la gestion, la structuration et la publication de la documentation. Ces fonctionnalités sont conçues pour répondre aux besoins des projets de documentation complexes et pour améliorer l'efficacité et la cohérence des documents produits. Cette section passe en revue les principales fonctionnalités d'Antora.

Génération de sites statiques

L'une des caractéristiques fondamentales d'Antora est sa capacité à générer des sites de documentation statiques. Ces sites sont construits à partir de sources Git, permettant ainsi une gestion de version fluide et une collaboration facile entre les contributeurs. Une fois généré, le site peut être déployé sur n'importe quel serveur web sans nécessiter de backend dynamique, ce qui améliore les performances et la sécurité.

Le schéma ci-dessous montre ce qui distingue Antora d'un générateur classique : le playbook désigne plusieurs dépôts Git et plusieurs branches, Antora les lit à distance, y ajoute le bundle d'interface, et produit un seul site où toutes les versions cohabitent.

Source · SVG

Échap pour fermer, + et − pour zoomer, défilement pour se déplacer. 100 % − Ajuster + Fermer

antora antora-playbook.yml

Gestion de versions

Antora excelle dans la gestion des versions de documentation. Chaque composant de documentation peut être versionné indépendamment, ce qui permet de maintenir des versions spécifiques de la documentation alignées avec les versions du logiciel. Cette fonctionnalité est particulièrement utile pour les projets en évolution rapide, où les fonctionnalités et les interfaces peuvent changer fréquemment.

content:
  sources:
    - url: https://github.com/votre-repo/documentation.git
      branches: [v1.0, v2.0, main]

Modularité

La modularité est un autre point fort d'Antora. La documentation est organisée en composants et modules, ce qui permet de structurer le contenu de manière logique et de le réutiliser facilement. Un composant est une collection de documents qui partagent un thème ou une fonction commune, tandis qu'un module est une subdivision d'un composant, regroupant des documents plus spécifiques.

Support d'AsciiDoc

Antora utilise AsciiDoc comme format principal pour les documents, offrant ainsi une syntaxe riche et puissante pour la rédaction de la documentation. AsciiDoc permet d'inclure des tableaux, des listes, des images, des blocs de code et bien plus encore, tout en restant lisible dans sa forme brute.

= Titre du Document
:author: Auteur
:revdate: 2024-06-17

== Introduction

Ceci est une introduction à notre documentation avec **Antora**.

Fichier de configuration (playbook)

Le playbook d'Antora est un fichier de configuration central qui définit les sources de documentation, les paramètres de génération de site et d'autres configurations nécessaires. Il permet de centraliser toutes les configurations requises pour générer et déployer le site de documentation.

site:
  title: Documentation du Projet
  start_page: mon-composant::index.adoc

content:
  sources:
    - url: https://github.com/votre-repo/documentation.git
      branches: [main]

output:
  dir: ./build/site

Thèmes personnalisables

Antora permet de personnaliser l'apparence du site de documentation à l'aide de thèmes, livrés sous forme de bundle d'interface (une archive ZIP). Vous pouvez utiliser le bundle par défaut publié par le projet ou créer le vôtre pour répondre aux besoins spécifiques de votre projet. La personnalisation peut inclure des styles CSS, des templates HTML et d'autres éléments visuels.

ui:
  bundle:
    url: https://github.com/votre-repo/antora-ui-bundle/releases/download/v1.0.0/ui-bundle.zip

Recherche intégrée

La recherche n'est pas active par défaut : le site généré n'en propose aucune tant que vous n'ajoutez pas l'extension Lunr d'Antora (@antora/lunr-extension), déclarée dans le playbook, qui construit un index côté client au moment de la génération. Elle devient vite indispensable sur une grande base de documentation, où la navigation manuelle est fastidieuse.

Dépendances et références croisées

Antora peut gérer les dépendances entre différents composants de documentation, permettant ainsi de créer des liens et des références croisées entre des documents situés dans des composants ou des modules différents. Cela facilite la création d'une documentation cohérente et interconnectée.

Intégration avec CI/CD

Antora s'intègre bien avec les pipelines CI/CD (Intégration Continue / Déploiement Continu), permettant une automatisation complète du processus de génération et de déploiement de la documentation. Cela garantit que la documentation est toujours à jour et disponible en ligne rapidement après chaque changement.

Extensibilité

Grâce à sa nature open-source, Antora est hautement extensible. Les utilisateurs peuvent développer et partager des extensions pour ajouter de nouvelles fonctionnalités ou améliorer les fonctionnalités existantes. Cette extensibilité permet à Antora de s'adapter aux besoins spécifiques de divers projets.

Concepts de base

Pour utiliser efficacement Antora, il est essentiel de comprendre ses concepts fondamentaux. Ces concepts permettent de structurer et de gérer la documentation de manière organisée et cohérente. Cette section détaille les principaux.

Les quatre notions s'emboîtent, et le schéma ci-dessous les montre dans cet ordre : le playbook désigne un dépôt, le dépôt contient un composant décrit par antora.yml, le composant se découpe en modules, et chaque module porte ses pages, sa navigation et ses images.

Source · SVG

Échap pour fermer, + et − pour zoomer, défilement pour se déplacer. 100 % − Ajuster + Fermer

Composants

Un composant dans Antora est une unité de documentation indépendante, qui regroupe des documents ayant un thème ou une fonction commune. Chaque composant peut avoir plusieurs versions, ce qui permet de maintenir des documents spécifiques à chaque version d'un logiciel ou d'un projet.

Par exemple, si vous documentez une application web, vous pouvez avoir un composant pour l'API, un autre pour la documentation utilisateur et un troisième pour les guides de développement.

Modules

Les modules sont des subdivisions des composants. Ils permettent d'organiser la documentation en unités logiques plus petites, comme des chapitres ou des sections. Chaque module contient un ensemble de fichiers de documentation, généralement en AsciiDoc, qui couvrent des sujets spécifiques.

Par exemple, dans un composant API, vous pouvez avoir des modules pour l'authentification, les points de terminaison de l'utilisateur et les erreurs courantes.

Pages

Les pages sont les documents individuels qui constituent les modules. Chaque page est un fichier AsciiDoc qui traite d'un sujet particulier. Les pages sont la plus petite unité de contenu dans Antora.

= Titre du Document
:author: Auteur
:revdate: 2024-06-17

== Introduction

Ceci est une introduction à notre documentation avec Antora.

Navigation

La navigation dans Antora est définie à l'aide de fichiers nav.adoc, déclarés dans le fichier antora.yml du composant, qui permettent de structurer la façon dont les utilisateurs parcourent la documentation. Ce sont de simples listes AsciiDoc dont chaque élément est un lien xref: vers une page.

* Guide d'utilisation
** xref:introduction.adoc[Introduction]
** xref:installation.adoc[Installation]

Playbook

Le playbook est un fichier de configuration central qui définit les sources de documentation, les paramètres de génération de site et d'autres configurations nécessaires. C'est le point de départ pour générer le site de documentation avec Antora.

site:
  title: Documentation du Projet
  start_page: mon-composant::index.adoc

content:
  sources:
    - url: https://github.com/votre-repo/documentation.git
      branches: [main]

output:
  dir: ./build/site

Pages d'index

Les pages d'index servent de points d'entrée pour les composants et les modules. Elles fournissent un aperçu du contenu et permettent de naviguer facilement entre les sections.

= Documentation du Projet

== Introduction

Bienvenue dans la documentation du Projet. Utilisez le menu pour naviguer à travers les différentes sections.

Variables et attributs

Les variables et attributs dans Antora permettent de personnaliser et de réutiliser des morceaux de texte ou des configurations dans plusieurs documents. Ils sont définis dans les fichiers AsciiDoc et peuvent être utilisés pour insérer des informations dynamiques comme des versions de logiciel ou des chemins de fichiers.

:project-name: MonProjet
:version: 1.0

= Documentation de {project-name} v{version}

Images et ressources

Antora permet d'inclure facilement des images et d'autres ressources dans la documentation. Les ressources peuvent être stockées dans des répertoires spécifiques et référencées dans les fichiers AsciiDoc.

image::logo.png[Mon Logo]

Liens et références

Les liens et références permettent de créer des connexions entre différentes parties de la documentation. Ils peuvent pointer vers des pages internes, des sections spécifiques ou des ressources externes.

Voir la documentation complète sur la page xref:installation.adoc[Installation].

Dépendances entre composants

Antora gère les dépendances entre différents composants et modules de documentation. Cela permet de créer des références croisées et de s'assurer que toutes les parties de la documentation sont cohérentes et à jour.

En comprenant ces concepts de base, vous serez en mesure de structurer et de gérer votre documentation avec Antora de manière efficace et organisée. Ces concepts forment la base sur laquelle repose toute la puissance et la flexibilité d'Antora.

Installation et configuration

Pour commencer à utiliser Antora, il est essentiel de suivre quelques étapes d'installation et de configuration. Cette section vous guide à travers l'installation d'Antora et la configuration initiale de votre projet de documentation.

Prérequis

Avant d'installer Antora, assurez-vous que vous avez les prérequis suivants :

• Node.js (une version LTS récente ; la version minimale exigée figure dans la documentation d'Antora)
• npm (Node Package Manager)

Vous pouvez vérifier les versions installées de Node.js et npm en utilisant les commandes suivantes :

node -v
npm -v

Installation d'Antora

Antora est distribué via npm (le gestionnaire de paquets de Node.js). Pour l'installer globalement sur votre système, utilisez la commande suivante :

npm install -g @antora/cli @antora/site-generator-default

Cette commande installe à la fois la CLI (Command Line Interface) d'Antora et le générateur de site par défaut.

Création de votre premier projet

Après avoir installé Antora, vous pouvez créer la structure de base de votre projet de documentation. Commencez par créer un répertoire pour votre projet :

mkdir mon-projet-doc
cd mon-projet-doc

Configuration du playbook

Le playbook est un fichier de configuration au format YAML (un format texte à base d'indentation) qui définit les sources de documentation, les paramètres de génération du site et d'autres configurations nécessaires. Créez un fichier nommé antora-playbook.yml dans votre répertoire de projet et ajoutez-y le contenu suivant :

site:
  title: Documentation de MonProjet
  start_page: mon-composant::index.adoc

content:
  sources:
    - url: https://github.com/votre-repo/documentation.git
      branches: [main]

ui:
  bundle:
    url: https://github.com/votre-repo/antora-ui-bundle/releases/download/v1.0.0/ui-bundle.zip

output:
  dir: ./build/site

Ce playbook spécifie les éléments suivants :

• title : Le titre de votre site de documentation.
• start_page : La page de démarrage de votre documentation, au format nom-du-composant::index.adoc.
• sources : Les sources de contenu, ici un dépôt Git.
• ui : Le bundle d'interface (le thème), une archive ZIP que le playbook doit toujours désigner.
• output : Le répertoire où le site généré sera stocké.

Structure des répertoires

La structure de votre projet doit suivre certaines conventions pour qu'Antora puisse l'interpréter correctement. Voici un exemple de structure de répertoires pour un dépôt qui contient un seul composant :

• Répertoiremon-projet-doc/

  • antora-playbook.yml
  • antora.yml
  • Répertoiremodules/

    • RépertoireROOT/

      • nav.adoc
      • Répertoirepages/

        • index.adoc

• antora.yml : Le descripteur du composant, qui lui donne son nom et sa version.
• modules/ROOT/pages/ : Contient les fichiers de documentation en AsciiDoc.
• nav.adoc : Fichier de navigation pour définir la structure du site.

Le descripteur antora.yml est indispensable : sans lui, Antora ne reconnaît pas le dossier comme un composant. Voici un exemple minimal :

name: mon-composant
title: Mon composant
version: '1.0'
nav:
  - modules/ROOT/nav.adoc

Ici, le dépôt de documentation contient un seul composant à sa racine ; un dépôt peut en contenir plusieurs, comme dans la section « Création de documentation ». Le module ROOT est le module par défaut : ses pages s'affichent à la racine du composant. Le name du composant est celui que reprend start_page dans le playbook.

Rédaction de la documentation

Commencez à rédiger votre documentation en créant des fichiers AsciiDoc. Par exemple, créez un fichier index.adoc dans le répertoire pages :

= Documentation de MonProjet
:author: Votre Nom
:revdate: 2024-06-17

== Introduction

Bienvenue dans la documentation de MonProjet. Ce document vous guidera à travers les fonctionnalités et l'utilisation de notre projet.

Génération du site

Pour générer le site de documentation, utilisez la commande suivante dans le répertoire de votre projet :

antora antora-playbook.yml

Cette commande lira le playbook, récupérera les sources de contenu et générera le site dans le répertoire spécifié (./build/site).

Vérification et débogage

Après la génération, vous pouvez ouvrir le fichier index.html dans votre navigateur pour vérifier que le site est correctement généré. Si vous rencontrez des erreurs, vérifiez les messages de la console pour identifier et résoudre les problèmes.

Automatisation avec npm scripts

Pour simplifier l'exécution des commandes, vous pouvez ajouter des scripts npm dans votre fichier package.json :

{
  "name": "mon-projet-doc",
  "version": "1.0.0",
  "scripts": {
    "build": "antora antora-playbook.yml",
    "serve": "http-server ./build/site"
  },
  "devDependencies": {
    "@antora/cli": "^3.1.0",
    "@antora/site-generator-default": "^3.1.0",
    "http-server": "^14.1.1"
  }
}

Ensuite, vous pouvez utiliser les commandes suivantes pour générer et servir votre site localement :

npm run build
npm run serve

Vous savez maintenant installer Antora, configurer un playbook et générer un premier site. Les sections qui suivent détaillent la création de contenu, la gestion des versions, la personnalisation de l'apparence et le déploiement.

Création de documentation

Une fois Antora installé et configuré, vous pouvez commencer à créer votre documentation. Cette section vous guide à travers le processus de structuration et de rédaction de la documentation en utilisant les concepts de base d'Antora.

Structuration des composants et modules

La première étape consiste à structurer votre documentation en composants et modules. Chaque composant représente une unité logique de votre projet, et chaque module est une subdivision du composant. Par exemple, si vous documentez une application web, vous pouvez avoir les composants suivants :

• API : Documentation de l'API
• Utilisateur : Guides et manuels pour les utilisateurs finaux
• Développeur : Guides pour les développeurs

Chaque composant peut contenir plusieurs modules. Pour structurer votre projet, créez les répertoires appropriés dans votre dépôt de documentation. Les trois composants ci-dessous ont la même forme, chacun avec son descripteur antora.yml et son module ROOT :

• Répertoiremon-projet-doc/

  • Répertoirecomposant-api/

    • antora.yml
    • Répertoiremodules/

      • RépertoireROOT/

        • nav.adoc
        • Répertoirepages/

          • index.adoc
  • Répertoirecomposant-utilisateur/

    • antora.yml
    • Répertoiremodules/

      • RépertoireROOT/

        • nav.adoc
        • Répertoirepages/

          • index.adoc
  • Répertoirecomposant-developpeur/

    • antora.yml
    • Répertoiremodules/

      • RépertoireROOT/

        • nav.adoc
        • Répertoirepages/

          • index.adoc

Chaque composant porte son propre antora.yml. Quand un même dépôt en contient plusieurs, la source du playbook l'indique avec start_paths, qui liste les dossiers où chercher un antora.yml :

content:
  sources:
    - url: .
      branches: main
      start_paths: composant-*

Rédaction des pages en AsciiDoc

AsciiDoc est le format utilisé par Antora pour les fichiers de documentation. Commencez à rédiger vos documents en créant des fichiers .adoc dans les répertoires pages de chaque module. Voici un exemple de fichier index.adoc pour le composant API :

= Documentation de l'API
:author: Votre Nom
:revdate: 2024-06-17

== Introduction

Cette section couvre la documentation de l'API de MonProjet. Vous y trouverez des informations sur les endpoints, les formats de requêtes et de réponses, ainsi que des exemples d'utilisation.

== Endpoints

=== Endpoint 1

Description de l'endpoint 1.

[source,json]
----
{
  "request": {
    "method": "GET",
    "url": "/api/endpoint1"
  },
  "response": {
    "status": 200,
    "body": {
      "message": "Réponse de l'endpoint 1"
    }
  }
}
----

=== Endpoint 2

Description de l'endpoint 2.

[source,json]
----
{
  "request": {
    "method": "POST",
    "url": "/api/endpoint2"
  },
  "response": {
    "status": 201,
    "body": {
      "id": "12345",
      "message": "Endpoint 2 créé"
    }
  }
}
----

Création du fichier de navigation

Pour chaque module, créez un fichier nav.adoc qui définira la structure de navigation de votre documentation. Voici un exemple pour le module API :

* Docs
** xref:index.adoc[Introduction]
** xref:endpoints.adoc[Endpoints]
** xref:auth.adoc[Authentification]

Inclusion d'images et de ressources

Antora permet d'inclure facilement des images et d'autres ressources dans votre documentation. Placez vos images dans le dossier images/ du module, à côté de pages/, et référencez-les dans vos fichiers AsciiDoc :

• Répertoiremon-projet-doc/

  • Répertoirecomposant-api/

    • Répertoiremodules/

      • RépertoireROOT/

        • Répertoirepages/

          • index.adoc
          • endpoints.adoc
        • Répertoireimages/

          • diagram.png

Dans votre fichier AsciiDoc, utilisez la syntaxe suivante pour inclure une image :

image::diagram.png[Diagramme de l'API]

Utilisation des variables et attributs

Les variables et attributs permettent de personnaliser et de réutiliser des morceaux de texte ou des configurations dans plusieurs documents. Définissez-les dans vos fichiers AsciiDoc :

:project-name: MonProjet
:version: 1.0

= Documentation de {project-name} v{version}
:author: Votre Nom
:revdate: 2024-06-17

== Introduction

Bienvenue dans la documentation de {project-name}.

Références croisées

Créez des références croisées pour lier différentes sections ou pages de votre documentation. Cela facilite la navigation et permet aux utilisateurs de trouver rapidement les informations connexes.

Voir la documentation complète sur la page xref:endpoints.adoc[Endpoints].

Validation et vérification

Après avoir rédigé vos documents, il est important de les valider pour s'assurer qu'ils sont correctement formatés et que toutes les références et inclusions fonctionnent comme prévu. Utilisez la commande de génération du site pour vérifier votre travail :

antora antora-playbook.yml

Ouvrez le site généré dans un navigateur pour vérifier que toutes les pages, images et liens fonctionnent correctement.

Votre documentation est structurée et rédigée. Reste à la faire vivre au rythme des versions du logiciel, ce que permet la gestion des versions d'Antora.

Gestion des versions

La gestion des versions est une fonctionnalité essentielle d'Antora, permettant de maintenir des documents précis et à jour pour différentes versions de votre projet. Cette section montre comment configurer et gérer les versions de votre documentation avec Antora.

Concept de versionnement

Antora permet de versionner la documentation en utilisant les branches de votre dépôt Git. Chaque branche peut représenter une version spécifique de votre projet et Antora générera la documentation en conséquence. Cela permet aux utilisateurs d'accéder facilement aux informations pertinentes pour la version spécifique de votre logiciel qu'ils utilisent.

Le numéro de version affiché n'est pas le nom de la branche : Antora le lit dans la clé version du fichier antora.yml présent sur chaque branche (par exemple version: '2.0' sur la branche v2.0). Une branche peut donc s'appeler librement, mais son antora.yml doit porter la bonne version.

Configuration du playbook pour le versionnement

Pour commencer, vous devez configurer votre playbook pour inclure les branches correspondant aux différentes versions de votre documentation. Modifiez le fichier antora-playbook.yml pour spécifier les branches de votre dépôt Git :

site:
  title: Documentation de MonProjet
  start_page: mon-composant::index.adoc

content:
  sources:
    - url: https://github.com/votre-repo/documentation.git
      branches: [v1.0, v2.0, main]

output:
  dir: ./build/site

Structuration des versions dans le dépôt Git

Assurez-vous que votre dépôt Git est structuré de manière à refléter les différentes versions de votre projet. Créez des branches pour chaque version majeure ou mineure de votre logiciel :

git checkout -b v1.0
git push origin v1.0

git checkout -b v2.0
git push origin v2.0

Utilisation des balises de version

Pour identifier clairement les versions dans vos documents, utilisez des balises de version dans les fichiers AsciiDoc. Par exemple, vous pouvez inclure des informations sur la version dans le titre du document :

= Documentation de MonProjet v1.0
:author: Votre Nom
:revdate: 2024-06-17

Gestion des changements entre versions

Il est important de documenter les changements entre les versions de votre logiciel. Créez une page dédiée aux notes de version ou aux changements pour chaque version :

= Notes de version pour MonProjet v1.0
:author: Votre Nom
:revdate: 2024-06-17

== Changements dans la version 1.0

* Ajout de la fonctionnalité X
* Amélioration de la performance pour Y
* Correction du bug Z

Génération de la documentation versionnée

Après avoir configuré les branches et les documents pour différentes versions, générez la documentation pour toutes les versions spécifiées dans le playbook. Utilisez la commande suivante :

antora antora-playbook.yml

Antora génère un site de documentation qui inclut toutes les versions spécifiées, permettant aux utilisateurs de naviguer facilement entre elles.

Navigation entre les versions

L'interface par défaut affiche un sélecteur de version sur chaque page du composant : vous n'avez rien à écrire dans nav.adoc pour passer d'une version à l'autre. Pour pointer explicitement vers une version précise depuis une page, préfixez le xref: par le numéro de version suivi de @ :

* xref:notes-de-version.adoc[Notes de version]
* xref:1.0@mon-composant::index.adoc[Documentation de la version 1.0]
* xref:2.0@mon-composant::index.adoc[Documentation de la version 2.0]

Exemple de fichier de navigation pour une version spécifique

Dans chaque branche, vous pouvez adapter le fichier nav.adoc pour refléter la structure spécifique de cette version :

* xref:index.adoc[Introduction]
* xref:installation.adoc[Installation]
* xref:utilisation.adoc[Utilisation]
* xref:changelog.adoc[Changelog]

Vérification des versions

Après avoir généré le site, vérifiez que toutes les versions sont correctement accessibles et que les liens fonctionnent comme prévu. Naviguez entre les différentes versions pour vous assurer que les utilisateurs peuvent facilement trouver les informations spécifiques à chaque version.

Mise à jour des versions

Lorsque vous publiez une nouvelle version de votre projet, créez une nouvelle branche Git et mettez à jour votre documentation en conséquence. Sur cette branche, pensez à passer la clé version d'antora.yml à '3.0'. N'oubliez pas de modifier le playbook pour inclure la nouvelle branche et de générer à nouveau le site de documentation.

git checkout -b v3.0
git push origin v3.0

Mettez à jour antora-playbook.yml :

content:
  sources:
    - url: https://github.com/votre-repo/documentation.git
      branches: [v1.0, v2.0, v3.0, main]

Puis régénérez le site :

antora antora-playbook.yml

Chaque version du logiciel dispose ainsi de sa documentation. Il reste à personnaliser l'apparence du site à l'aide de thèmes.

Thématisation

La thématisation permet de personnaliser l'apparence de votre site de documentation pour qu'il corresponde à l'identité visuelle de votre projet ou organisation. Antora offre une flexibilité considérable pour créer et appliquer des thèmes personnalisés. Cette section montre comment utiliser et créer des thèmes dans Antora.

Utilisation des thèmes par défaut

Antora n'embarque pas de thème : le playbook doit toujours désigner un bundle d'interface, une archive ZIP qui contient les styles, les templates et les scripts du site. Le projet Antora publie un bundle par défaut, antora-ui-default, que vous pouvez référencer par son URL dans le playbook :

ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

Pour utiliser votre propre thème, remplacez cette URL par celle de votre archive ZIP, comme dans le playbook d'installation plus haut.

Structure d'un thème Antora

Un thème Antora est un package qui contient les fichiers de style, les templates et les ressources nécessaires pour personnaliser l'apparence du site. Voici une structure de base pour un thème Antora :

• Répertoireantora-ui-bundle/

  • Répertoireassets/

    • Répertoirecss/

      • styles.css
    • Répertoireimages/

      • logo.png
  • Répertoirelayouts/

    • default.hbs
    • page.hbs
  • Répertoirepartials/

    • footer.hbs
    • header.hbs
  • package.json

Création d'un thème personnalisé

Pour créer votre propre thème, commencez par cloner un thème existant ou créez un nouveau répertoire pour votre thème. Voici un exemple de fichier package.json pour un thème Antora :

{
  "name": "antora-ui-bundle",
  "version": "1.0.0",
  "description": "Un thème personnalisé pour Antora",
  "main": "index.js",
  "author": "Votre Nom",
  "license": "MIT",
  "dependencies": {
    "handlebars": "^4.7.6"
  }
}

Personnalisation des styles

Pour personnaliser les styles, modifiez les fichiers CSS dans le répertoire assets/css. Vous pouvez ajouter vos propres styles ou modifier les styles existants pour correspondre à l'identité visuelle de votre projet.

body {
  font-family: Arial, sans-serif;
  background-color: #f5f5f5;
}

header {
  background-color: #333;
  color: white;
  padding: 10px 0;
}

header img {
  max-height: 50px;
}

footer {
  background-color: #333;
  color: white;
  text-align: center;
  padding: 10px 0;
}

Modification des templates

Antora utilise Handlebars, un moteur de gabarits qui remplace des expressions comme {{title}} par les valeurs de chaque page, pour les templates. Les fichiers de template dans le répertoire layouts définissent la structure HTML de vos pages. Vous pouvez modifier ces fichiers pour personnaliser la disposition de votre site.

Par exemple, le fichier default.hbs peut ressembler à ceci :

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{{title}}</title>
  <link rel="stylesheet" href="{{rootPath}}/assets/css/styles.css">
</head>
<body>
  <header>
    <div class="container">
      <img src="{{rootPath}}/assets/images/logo.png" alt="Logo">
      <h1>{{title}}</h1>
    </div>
  </header>
  <main>
    {{{content}}}
  </main>
  <footer>
    <div class="container">
      <p>&copy; 2024 MonProjet. Tous droits réservés.</p>
    </div>
  </footer>
</body>
</html>

Gestion des ressources

Les images du thème (logo, icônes) se placent dans le répertoire assets/images du bundle et se référencent depuis les templates, comme le <img> de l'exemple de default.hbs ci-dessus. Les images du contenu, elles, vivent dans le dossier images de chaque module, comme vu plus haut : ne les mélangez pas avec celles du thème.

Application du thème

Après avoir créé et personnalisé votre thème, mettez-le à jour dans votre dépôt Git et configurez le playbook pour utiliser ce thème :

ui:
  bundle:
    url: https://github.com/votre-repo/antora-ui-bundle/releases/download/v1.0.0/ui-bundle.zip

Test du thème

Générez votre site de documentation avec le nouveau thème pour voir les modifications appliquées :

antora antora-playbook.yml

Ouvrez le site généré dans un navigateur pour vérifier que le thème est correctement appliqué et que toutes les personnalisations fonctionnent comme prévu.

Exemple de thème personnalisé

Voici un exemple de thème personnalisé minimaliste pour Antora, réduit à une feuille de style, un logo et un seul layout :

• Répertoireantora-ui-bundle/

  • Répertoireassets/

    • Répertoirecss/

      • styles.css
    • Répertoireimages/

      • logo.png
  • Répertoirelayouts/

    • default.hbs
  • package.json

Avec le fichier styles.css suivant :

body {
  font-family: 'Open Sans', sans-serif;
  background-color: #ffffff;
  color: #333;
}

header {
  background-color: #4CAF50;
  color: white;
  padding: 10px 0;
}

header img {
  max-height: 50px;
}

footer {
  background-color: #4CAF50;
  color: white;
  text-align: center;
  padding: 10px 0;
}

Et le fichier default.hbs :

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{{title}}</title>
  <link rel="stylesheet" href="{{rootPath}}/assets/css/styles.css">
</head>
<body>
  <header>
    <div class="container">
      <img src="{{rootPath}}/assets/images/logo.png" alt="Logo">
      <h1>{{title}}</h1>
    </div>
  </header>
  <main>
    {{{content}}}
  </main>
  <footer>
    <div class="container">
      <p>&copy; 2024 MonProjet. Tous droits réservés.</p>
    </div>
  </footer>
</body>
</html>

Votre site de documentation Antora correspond désormais à l'identité visuelle de votre projet. Il reste à le mettre en ligne.

Déploiement

Après avoir généré et personnalisé votre site de documentation avec Antora, l'étape suivante consiste à le déployer sur un serveur web afin qu'il soit accessible aux utilisateurs. Cette section présente les différentes méthodes pour déployer votre site de documentation.

Préparation des fichiers

Avant de déployer votre site, assurez-vous que tous les fichiers nécessaires ont été générés et sont prêts à être copiés sur le serveur. Le répertoire de sortie défini dans votre playbook (./build/site par défaut) contient tous les fichiers de votre site de documentation.

Déploiement sur un serveur web

La méthode la plus simple pour déployer votre site de documentation est de copier les fichiers générés sur un serveur web. Voici quelques options populaires pour le déploiement :

Serveur Apache ou Nginx

Pour déployer votre site sur un serveur Apache ou Nginx, vous devez copier le contenu du répertoire de sortie vers le répertoire racine du serveur web.

Apache

1. Copiez les fichiers de votre site vers le répertoire racine d'Apache, généralement /var/www/html :

   sudo cp -r ./build/site/* /var/www/html/

2. Redémarrez Apache pour appliquer les modifications :

   sudo systemctl restart apache2

Nginx

1. Copiez les fichiers de votre site vers le répertoire racine de Nginx, généralement /usr/share/nginx/html :

   sudo cp -r ./build/site/* /usr/share/nginx/html/

2. Redémarrez Nginx pour appliquer les modifications :

   sudo systemctl restart nginx

Serveur GitHub Pages

GitHub Pages est une solution populaire pour héberger des sites statiques directement depuis un dépôt GitHub. Pour déployer votre site de documentation sur GitHub Pages :

1. Initialisez un nouveau dépôt Git dans le répertoire de sortie :

   cd ./build/site
   git init

2. Ajoutez tous les fichiers et effectuez un commit :

   git add .
   git commit -m "Initial commit"

3. Ajoutez l'URL de votre dépôt GitHub comme dépôt distant :

   git remote add origin https://github.com/votre-utilisateur/votre-repo.git

4. Poussez les fichiers vers la branche gh-pages :

   git push -u origin HEAD:gh-pages

Votre site sera alors disponible à l'URL https://votre-utilisateur.github.io/votre-repo.

Serveur Netlify

Netlify est un service de déploiement et d'hébergement pour les sites statiques. Pour déployer votre site de documentation sur Netlify :

1. Connectez-vous à Netlify et créez un nouveau site en sélectionnant votre dépôt GitHub.
2. Configurez les paramètres de construction :
   • Build command : antora antora-playbook.yml
   • Publish directory : ./build/site
3. Déployez le site.

Netlify déclenchera automatiquement le processus de construction et déploiera votre site.

Déploiement continu avec CI/CD

Pour automatiser le déploiement de votre site de documentation à chaque modification, vous pouvez utiliser des pipelines de CI/CD (Intégration Continue / Déploiement Continu). Voici un exemple de configuration pour GitHub Actions :

1. Créez un fichier .github/workflows/deploy.yml dans votre dépôt :

   name: Deploy Documentation
   
   on:
     push:
       branches:
         - main
   
   permissions: {}
   
   jobs:
     build:
       runs-on: ubuntu-24.04
       permissions:
         contents: write
   
       steps:
         - name: Checkout repository
           uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
           with:
             persist-credentials: false
   
         - name: Set up Node.js
           uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020  # v7.0.0
           with:
             node-version: '22'
   
         - name: Install Antora
           run: npm install -g @antora/cli @antora/site-generator-default
   
         - name: Build documentation
           run: antora antora-playbook.yml
   
         - name: Deploy to GitHub Pages
           uses: peaceiris/actions-gh-pages@84c30a85c19949d7eee79c4ff27748b70285e453 # v4.1.0
           with:
             github_token: ${{ secrets.GITHUB_TOKEN }}
             publish_dir: ./build/site

2. Commitez et poussez ce fichier dans votre dépôt GitHub. Chaque fois que vous poussez une modification sur la branche main, GitHub Actions générera et déploiera automatiquement votre site de documentation sur GitHub Pages.

Vérification du déploiement

Après avoir déployé votre site, vérifiez que tout fonctionne correctement en visitant l'URL où votre site est hébergé. Assurez-vous que toutes les pages, liens et ressources (images, fichiers CSS, etc.) s'affichent correctement.

Maintenance et mises à jour

Assurez-vous de maintenir votre site de documentation à jour en redéployant à chaque modification importante de votre projet ou de votre documentation. Automatisez autant que possible les processus de génération et de déploiement pour réduire les erreurs et garantir que les utilisateurs disposent toujours des informations les plus récentes.

À retenir

Les points essentiels de cette leçon :

• Antora génère un site statique à partir de fichiers AsciiDoc stockés dans des dépôts Git, sans backend à exploiter ;
• un composant regroupe des documents, un module le subdivise, une page est un fichier .adoc ;
• le playbook (antora-playbook.yml) décrit les sources, l'interface et le répertoire de sortie ; antora antora-playbook.yml produit le site ;
• chaque branche Git listée par le playbook devient une version de la documentation, dont le numéro est lu dans la clé version du fichier antora.yml de cette branche, pas dans le nom de la branche ;
• la recherche n'existe pas par défaut : elle s'ajoute avec l'extension Lunr déclarée dans le playbook ;
• l'apparence vient d'un bundle d'interface (le thème), référencé dans le playbook et modifiable avec CSS et templates Handlebars ;
• le dossier généré (build/site) se déploie tel quel sur Apache, Nginx, GitHub Pages ou Netlify ;
• une chaîne CI/CD régénère et publie le site à chaque modification, ce qui garde la documentation à jour sans geste manuel.

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

×

📖 Voir la documentation →