Éditer avec Decap CMS

Decap CMS est l’interface web qui permet de modifier cette documentation sans toucher au code : on choisit une page, on la modifie dans un formulaire, on publie. Chaque publication est enregistrée dans le dépôt Bitbucket, puis le site est reconstruit automatiquement.

Cette page décrit l’utilisation au quotidien. Le fonctionnement interne et l’installation sont décrits dans Decap CMS : architecture et mise en production.

Se connecter

L’interface se trouve à l’adresse /admin/ du site (par exemple https://doc.exemple.com/admin/).

• En production, le bouton propose de se connecter avec Bitbucket : une fenêtre s’ouvre pour autoriser l’accès, puis se referme. Il faut un compte Bitbucket ayant le droit d’écriture sur le dépôt.
• En local (développeurs), le bouton « Se connecter » donne accès directement, sans identifiant. Voir Essayer en local.

Trouver une page

Après la connexion, la colonne de gauche liste les collections : une par section du site (Guides, Comprendre Astro & Starlight, CMS, Référence, Annexes), et pour chacune sa version anglaise, marquée (EN). Un clic sur une collection affiche ses pages.

• Le champ Tout rechercher cherche dans toutes les collections.
• Trier par permet de classer les pages par titre ou par ordre dans le menu.
• Seules les pages au format Markdown (.md) apparaissent. Les quelques pages qui utilisent des composants avancés (comme la page d’accueil) sont modifiées directement dans le code.

L’écran d’édition

Un clic sur une page ouvre l’éditeur : le formulaire à gauche, un aperçu à droite.

La barre du haut indique l’état de la page :

Indication	Signification
MODIFICATIONS ENREGISTRÉES	La page affichée correspond à la version publiée
MODIFICATIONS NON ENREGISTRÉES	Des changements sont en cours et ne sont pas encore publiés
Publiée	La page est en ligne

Note

L’aperçu de droite montre le contenu, mais pas la mise en page du site : polices, couleurs et encarts y sont simplifiés. Le résultat final est visible sur le site après publication. L’icône en forme d’œil masque l’aperçu pour élargir le formulaire.

Les informations de la page

En haut du formulaire se trouvent les informations qui décrivent la page :

Champ	Rôle
Nom du fichier	Nom du fichier de la page, en anglais, qui donne aussi son adresse. Voir Créer une page.
Titre	Titre de la page, affiché en haut de la page et dans le menu. Obligatoire.
Description	Résumé d’une phrase, utilisé par les moteurs de recherche.
Barre latérale → Ordre	Position de la page dans le menu : les petits nombres en premier.
Barre latérale → Masquer du menu	La page reste accessible par son adresse, mais n’apparaît pas dans le menu.
Brouillon	La page est enregistrée mais n’est pas publiée sur le site.

Rédiger le contenu

Le champ Contenu est un éditeur de texte avec une barre d’outils : gras, italique, barré, code, lien, titres (H), citation, listes à puces et numérotées.

L’interrupteur Texte enrichi / Markdown permet de choisir le mode d’édition :

• Texte enrichi (par défaut) : on voit directement la mise en forme, comme dans un traitement de texte.
• Markdown : on voit le texte source, avec sa syntaxe (**gras**, ## Titre…).

Utiliser les boutons en mode Texte enrichi

En mode Texte enrichi, taper la syntaxe Markdown au clavier ne fonctionne pas : **gras** reste affiché tel quel, avec ses astérisques. Il faut sélectionner le texte et utiliser le bouton B, ou passer en mode Markdown.

Insérer un bloc

Le bouton + de la barre d’outils insère un bloc à l’emplacement du curseur :

Bloc	Usage
Code Block	Un exemple de code ou de commande, affiché dans un cadre avec un bouton de copie
Encart	Une note, une astuce ou un avertissement mis en valeur
Image	Une image, choisie dans la médiathèque ou téléversée

Les encarts

Un encart apparaît dans l’éditeur comme un bloc avec son propre petit formulaire :

• Type : Note (information complémentaire), Astuce, Attention ou Danger, chacun avec sa couleur sur le site.
• Titre : facultatif ; à défaut, le nom du type est affiché.
• Contenu : le texte de l’encart, avec sa propre barre d’outils.

Voici le rendu sur le site :

Un exemple d’encart

Cet encart est de type Astuce, avec un titre personnalisé.

Les images

Le bloc Image ouvre la médiathèque, également accessible par l’onglet Media en haut de l’écran :

• Téléverser une nouvelle ressource ajoute une image depuis l’ordinateur.
• Un clic sur une image puis sur Choisir la sélection l’insère dans la page.
• Penser à remplir le texte alternatif de l’image : il décrit l’image aux personnes qui ne la voient pas.

Les images sont automatiquement compressées lors de la construction du site : inutile de les réduire avant.

Créer une page

Dans la liste d’une collection, le bouton + Guide (ou + Page, selon la collection) ouvre un formulaire vide :

• Le champ Nom du fichier donne le nom du fichier, et donc l’adresse de la page : install donne /guides/install/. Il s’écrit en anglais, en minuscules, chiffres et tirets, quelle que soit la langue de la page : c’est ce qui permet de relier une page à sa traduction. Un nom mal formé est refusé à la publication.
• Ce nom n’est pris en compte qu’à la création : le modifier ensuite ne renomme pas la page.
• La page apparaît automatiquement dans le menu du site, à la position indiquée par le champ Ordre.

Publier

Dès qu’une modification est faite, le bouton Publier apparaît. Sa flèche ouvre trois choix :

Choix	Effet
Publier maintenant	Enregistre la page
Publier et créer une nouvelle entrée	Enregistre, puis ouvre un formulaire vide dans la même collection
Publier et dupliquer	Enregistre, puis ouvre une copie de la page, à adapter

Publier crée un enregistrement (commit) dans le dépôt Bitbucket. Le site est ensuite reconstruit et mis en ligne automatiquement : la modification est visible après quelques minutes.

Rien n’est jamais perdu

Chaque publication étant enregistrée dans l’historique Git, toute version précédente d’une page peut être retrouvée, même après une suppression avec le bouton Supprimer l’entrée.

Traduire une page

Le site existe en français et en anglais. Chaque section a deux collections dans le CMS, par exemple Guides et Guides (EN) : une page et sa traduction sont deux entrées distinctes, reliées par le même Nom du fichier.

Voici la page « Démarrage », dans la collection Guides :

Et sa traduction, dans la collection Guides (EN), avec le même nom de fichier :

Pour traduire une page :

1. Ouvrir la page d’origine, et noter son Nom du fichier (ici getting-started).
2. Dans la collection (EN) de la même section, cliquer sur + pour créer une page.
3. Saisir exactement le même Nom du fichier, puis traduire le titre, la description et le contenu.
4. Reprendre le même Ordre dans la barre latérale, pour que les menus des deux langues se correspondent.
5. Publier.

Sur le site, la page anglaise est publiée sous /en/…, et le sélecteur de langue de l’en-tête permet de passer d’une version à l’autre :

Tant qu’une page n’est pas traduite, sa version anglaise affiche le contenu français avec un avertissement, et son titre français apparaît dans le menu anglais :

Garder les deux versions alignées

Le CMS ne relie pas automatiquement une page à sa traduction : une modification de la page française doit être reportée à la main dans la page anglaise. Les raisons de ce fonctionnement sont détaillées dans l’annexe sur l’internationalisation.

En résumé

1. Ouvrir /admin/ et se connecter avec Bitbucket.
2. Choisir la collection (française, ou (EN) pour l’anglais), puis la page (ou créer une page avec +).
3. Modifier le formulaire et le contenu ; insérer encarts et images avec le bouton +.
4. Cliquer sur Publier → Publier maintenant.
5. Vérifier le résultat sur le site quelques minutes plus tard.