Éditeur visuel

Créez, gérez et publiez votre documentation dans votre navigateur

Accédez à l’éditeur visuel depuis votre Dashboard pour gérer votre documentation directement dans votre navigateur.

• Édition WYSIWYG (What You See Is What You Get): Modifiez votre documentation avec un éditeur visuel qui affiche le rendu final tel qu’il sera publié.
• Synchronisation Git: Toutes les modifications sont automatiquement synchronisées avec votre référentiel Git pour assurer le contrôle de version.
• Collaboration d’équipe: Plusieurs personnes peuvent travailler simultanément sur la documentation.
• Intégration de composants: Ajoutez des encadrés, des code blocks et d’autres composants avec des commandes au slash.
• Aucune configuration requise: Commencez à rédiger immédiatement depuis votre Dashboard.

​

Vue d’ensemble

Voici comment vous travaillerez généralement dans l’éditeur visuel :

1. Choose your branch

   Créez une branche ou apportez des modifications directement à votre branche de déploiement. Nous recommandons de créer une branche afin de pouvoir prévisualiser vos modifications avant leur mise en ligne.

2. Open your file

   Ouvrez un fichier existant dans la barre latérale ou créez-en un nouveau à l’aide de l’explorateur de fichiers.

3. Edit your content

   Modifiez votre contenu dans l’éditeur visuel. Appuyez sur / pour ouvrir le menu des composants.

4. Preview your changes

   Le mode visuel montre comment vos modifications apparaîtront sur votre site en production. Utilisez-le pour vérifier que tout est correct.

5. Publish your changes

   Si vous travaillez sur votre branche de déploiement, publiez vos modifications directement depuis l’éditeur visuel. Sur les autres branches, créez une pull request (demande de fusion) pour relecture avant publication.

​

Modes de l’éditeur

L’éditeur visuel propose deux modes pour s’adapter à différentes préférences et besoins d’édition : mode visuel et Mode Markdown.

Utilisez le commutateur de mode dans la barre d’outils de l’éditeur pour changer de mode.

​

Mode visuel

Le mode visuel offre une expérience WYSIWYG (What You See Is What You Get) où les modifications apportées dans l’éditeur reflètent l’apparence de votre documentation publiée. Ce mode est idéal lorsque vous souhaitez voir en temps réel à quoi ressembleront vos modifications.

​

Mode Markdown

Le Mode Markdown donne un accès direct au code MDX sous-jacent de votre documentation. Ce mode est idéal lorsque vous avez besoin d’un contrôle précis des propriétés des composants ou lorsque vous préférez écrire en syntaxe Markdown.

​

Gérer l’objet

​

Parcourez vos fichiers

Utilisez l’explorateur de fichiers de la barre latérale pour parcourir vos fichiers de documentation. Cliquez sur un fichier pour l’ouvrir dans l’éditeur.

Appuyez sur Command + P sur macOS ou Ctrl + P sur Windows pour rechercher des fichiers par nom.

​

Créer de nouvelles pages

Sélectionnez l’icône Create a new file dans la barre latérale de l’explorateur de fichiers.

Les noms de fichiers sont automatiquement suffixés par l’extension .mdx. Pour changer le type de fichier, cliquez sur l’extension. Sélectionnez le type de fichier souhaité dans le menu déroulant.

​

Renommer des pages

Pour renommer une page, cliquez sur l’icône du menu kebab du fichier à renommer. Sélectionnez Renommer dans le menu déroulant.

​

Supprimer des pages

Pour supprimer une page, cliquez sur l’icône de menu à trois points du fichier que vous souhaitez supprimer. Sélectionnez Supprimer dans le menu déroulant.

​

Organisez votre navigation

Modifiez votre fichier docs.json pour ajouter de nouvelles pages et retirer les pages supprimées de la navigation de votre site. Consultez Navigation pour plus d’informations sur l’organisation des pages.

Exemple : ajouter une page Themes au groupe Profile

Dans cet exemple, vous avez créé une nouvelle page intitulée Themes et vous souhaitez l’ajouter au groupe Profile de votre documentation. Ajoutez le chemin de la nouvelle page au tableau pages du groupe Profile dans votre fichier docs.json pour qu’elle apparaisse dans la navigation de votre site.

Adding a Themes page to the Profile group

{
    "navigation": {
        "groups": [
            {
                "group": "Prise en main",
                "pages": [
                    "index",
                    "quickstart",
                    "installation"
                ]
            },
            {
                "group": "Profil",
                "pages": [
                    "settings",
                    "account-types",
                    "dashboard",
                    "themes"
                ]
            }
        ]
    }
}

​

Modifier le contenu

Modifiez vos pages en mode visuel ou en Mode Markdown dans l’éditeur.

En mode visuel, appuyez sur / pour ouvrir le menu des composants. Ajoutez des blocs de contenu, des encadrés d’information, des blocs de code et d’autres composants pour personnaliser votre documentation.

En Mode Markdown, vous modifiez directement le MDX de vos pages. Cela peut être utile lorsque vous devez :

• Définir des propriétés spécifiques de composants
• Travailler avec des composants imbriqués complexes
• Copier-coller du contenu MDX depuis d’autres sources

Consultez Mettre en forme le texte et Mettre en forme le code pour en savoir plus sur l’écriture avec la syntaxe Markdown.

​

Publier vos modifications

La branche sur laquelle vous travaillez détermine la façon dont l’éditeur publie vos modifications :

• Branche de déploiement : la publication met immédiatement à jour votre site en ligne.
• Autres branches : la publication crée un pull request (demande de fusion) afin que vous puissiez examiner les modifications avant de les déployer en production.

​

Pull requests et revue des modifications

Les pull requests (demandes de fusion) vous permettent de proposer des modifications depuis votre branche afin que d’autres puissent les examiner avant de les fusionner dans votre documentation en production. Cela aide à garantir l’exactitude de vos modifications et offre à votre équipe l’occasion de collaborer sur le contenu.

Même si vous travaillez seul, les pull requests sont utiles pour prévisualiser les modifications et maintenir un historique des mises à jour clair.

​

Créer une pull request

1. Enregistrer votre travail

   Sélectionnez Enregistrer les modifications pour enregistrer toutes les modifications sur votre branche.

2. Créer la pull request

   Sélectionnez Publier la pull request dans la barre d’outils de l’éditeur.

3. Ajouter un title et une description

   Rédigez un title et une description clairs expliquant :

   • Les modifications que vous avez apportées
   • Pourquoi vous les avez apportées
   • Les éléments spécifiques qui nécessitent une relecture
4. Créer et partager

   Sélectionnez Publier la pull request. L’éditeur fournira un lien pour afficher votre pull request.

   

​

Examiner les pull requests

Une fois votre pull request créée :

1. Passer en revue les modifications : Vous et les membres de votre équipe pouvez examiner votre pull request dans votre fournisseur Git, comme GitHub ou GitLab.
2. Laisser des commentaires : Ajoutez des commentaires ou demandez des changements.
3. Apporter des modifications supplémentaires : Apportez des modifications supplémentaires dans l’éditeur visuel. Lorsque vous enregistrez les modifications, l’éditeur les envoie vers votre pull request.
4. Approuver : Approuvez la pull request lorsque vous êtes satisfait des changements.
5. Fusionner : Fusionnez la pull request lorsque vous êtes prêt à déployer vos changements en production.

​

Raccourcis clavier

L’éditeur visuel prend en charge tous les raccourcis clavier courants comme copier, coller, annuler et tout sélectionner, ainsi que les raccourcis suivants :

Commande	macOS	Windows
Rechercher des fichiers	Cmd + P	Control + P
Ajouter un lien au texte sélectionné	Cmd + K	Control + K
Insérer un saut de ligne	Cmd + Enter	Control + Enter
Gras	Cmd + B	Control + B
Italique	Cmd + I	Control + I
Souligné	Cmd + U	Control + U
Barré	Cmd + Shift + S	Control + Shift + S
Code	Cmd + E	Control + E
Texte normal	Cmd + Alt + 0	Control + Alt + 0
Titre 1	Cmd + Alt + 1	Control + Alt + 1
Titre 2	Cmd + Alt + 2	Control + Alt + 2
Titre 3	Cmd + Alt + 3	Control + Alt + 3
Titre 4	Cmd + Alt + 4	Control + Alt + 4
Liste numérotée	Cmd + Shift + 7	Control + Shift + 7
Liste à puces	Cmd + Shift + 8	Control + Shift + 8
Bloc de citation	Cmd + Shift + B	Control + Shift + B
Indice	Cmd + ,	Control + ,
Exposant	Cmd + .	Control + .

​

Dépannage

Trouvez des solutions aux problèmes courants que vous pourriez rencontrer avec l’éditeur visuel.

Les modifications n’apparaissent pas après publication

Causes possibles :

• Le déploiement est toujours en cours
• Problèmes de cache du navigateur
• Erreurs de build ou de déploiement

Solutions :

1. Vérifiez l’état du déploiement dans votre Dashboard.
2. Effectuez une actualisation forcée de votre navigateur (Ctrl + F5 ou Cmd + Shift + R)
3. Videz le cache de votre navigateur.

Erreurs d’autorisation lors de la publication

Causes possibles :

• Permissions insuffisantes sur le référentiel Git
• Problèmes d’authentification avec votre fournisseur Git

Solutions :

1. Vérifiez que vous disposez des accès appropriés au référentiel.
2. Assurez-vous que votre intégration Git est correctement configurée.
3. Consultez la documentation Editor Permissions.

Problèmes de chargement de l’éditeur

Causes possibles :

• Problèmes de connectivité réseau
• Référentiels de documentation volumineux

Solutions :

1. Vérifiez votre connexion internet.
2. Actualisez la page.
3. Contactez le support si le problème persiste.

Les fichiers ne se chargent pas ou affichent des erreurs

Causes possibles :

• Syntaxe MDX invalide dans les fichiers
• Fichiers manquants ou corrompus
• Fichiers volumineux provoquant des expirations

Solutions :

1. Vérifiez la syntaxe du fichier pour détecter d’éventuelles erreurs de formatage MDX.
2. Vérifiez que le fichier existe dans votre référentiel.

​

Prochaines étapes

• Découvrez les concepts fondamentaux de Git
• Découvrez les meilleures pratiques de collaboration avec des branches