Rédiger vos documentations avec docs.page et GitHub

Premiers pas avec docs.page

Créer un compte GitHub

Pour commencer, si vous n'avez pas encore de compte GitHub, il vous faudra en créer un. Une fois cette étape accomplie, vous pourrez créer votre dépôt public Git. Pour ceux qui manquent d'expérience à ce sujet, je vous encourage à consulter la documentation officielle fournie par GitHub.

Structure de votre dépôt

Pour que docs.page fonctionne correctement, vous devez ajouter un dossier nommé docs à la racine de votre dépôt. Afin de simplifier la configuration de docs.page, la société Invertase, créatrice de docs.page, a mis en place un outil pratique qui permet, via Node.js et npm, de créer la structure de base de votre documentation.

Pour ce faire, exécutez la commande suivante à la racine de votre dépôt :

Cet outil génèrera automatiquement les fichiers et dossiers nécessaires. Vous devriez voir apparaître dans votre dépôt la structure de dossier suivante :

• docs
  • another-page.mdx
  • index.mdx
• docs.json

Après avoir envoyé votre code sur la branche main de votre dépôt, vous pouvez dès à présent accéder à votre documentation en ligne via https://docs.page/ suivi de l'organisation GitHub et du nom de dépôt Git : 

Par exemple, https://github.com/TeddyVermeulin/lamp-doc deviendra https://docs.page/TeddyVermeulin/lamp-doc.

Configuration de votre espace de documentation

Vous pouvez apporter quelques éléments de personnalisation via le fichier docs.json. Ce fichier permet de configurer plusieurs aspects de votre documentation afin de l'adapter à vos besoins spécifiques. Par exemple, vous pouvez définir le titre de votre documentation, ajouter des liens de navigation, configurer des thèmes pour harmoniser le design avec votre charte graphique, et même intégrer des plugins pour ajouter des fonctionnalités supplémentaires.

Dans cet exemple, le titre de la documentation est défini par "name": "Mon projet", et la couleur dominante des liens a été modifiée avec "theme": "#DD007E". Les logos ont été modifiés. La navigation est structurée avec des liens vers l'accueil, le guide de démarrage et la configuration.

En ajustant ces paramètres dans votre fichier docs.json, vous pouvez personnaliser l'apparence et les fonctionnalités de votre documentation pour mieux répondre aux attentes de vos utilisateurs.

Vous trouverez une liste exhaustive des options de configuration sur la documentation de docs.page.

Pour aller plus loins

L'outil de recherche embarqué, signé par Algolia

L'un des atouts majeurs de docs.page est l'intégration de l'outil gratuit DocSearch, propulsé par Algolia. Algolia est reconnu pour ses capacités de recherche rapide et pertinente, offrant ainsi aux utilisateurs une expérience de navigation optimisée. Grâce à cette intégration, la recherche dans votre documentation devient instantanée et extrêmement précise, permettant aux utilisateurs de trouver rapidement les informations dont ils ont besoin. 

Algolia analyse en temps réel le contenu de votre documentation et génère des résultats de recherche pertinents, même pour les requêtes complexes. De plus, l'intégration est facile à configurer via le fichier docs.json, où vous pouvez spécifier les clés API nécessaires pour activer le service. Cette fonctionnalité améliore considérablement l'accessibilité et l'efficacité de votre documentation, en rendant chaque page et chaque section facilement trouvable.

Voyons plus en détails comment mettre en place DocSearch :

1. S'inscrire sur DocSearch
   Pour commencer, rejoignez le programme DocSearch en fournissant l'URL de votre documentation et votre adresse e-mail. Après quelques heures d'attente, vous recevrez un courriel d'Algolia vous fournissant votre appId, votre apiKey et votre indexName.
    
2. Ajouter les informations à votre fichier de configuration
   Dans le fichier de configuration de votre projet docs.json, ajoutez vos informations d'identification à l'objet docsearch :

Utilisation d'un domaine personnalisé

L'une des fonctionnalités de docs.page qui en font un outil vraiment intéressant est la possibilité de configurer un domaine personnalisé pour votre documentation. Cela permet de renforcer votre image de marque et d'offrir une expérience utilisateur cohérente. En utilisant un domaine personnalisé, vos utilisateurs peuvent accéder à votre documentation via une URL dédiée, telle que docs.monsite.com, au lieu d'une adresse générique.

Pour cela, il y a deux étapes à réaliser :

1. Modification des DNS de votre nom de domaine
   La première étape consiste à pointer votre domaine vers domains.docs.page via un enregistrement CNAME. Via votre fournisseur de domaine, créez un enregistrement DNS :
   @ | CNAME | domains.docs.page
    
2. Ajout de votre domaine au dépôt de docs.page
   La seconde étape est d'effectuer une demande de fusion de branches (pull request) pour modifier le fichier domains.json à la racine du dépôt docs.page. Créez une nouvelle entrée de tableau, en ajoutant votre domaine suivi de l'organisation et du dépôt GitHub, par exemple :

Dans le cadre de la rédaction de cet article, j'ai soumis une demande de fusion de branche sur GitHub. Actuellement, ma demande est en attente d'approbation par l'équipe d'Invertase. Je ne connais pas encore les critères exacts de vérification qu'ils appliquent aux demandes de fusion, ni leur taux d'acceptation. Néanmoins, après 24 heures, le statut reste inchangé. Dès que j'aurai plus de détails sur ce processus, je mettrai à jour cet article pour partager ces informations.

# MISE À JOUR LE 06/06/2024
Après une attente d'environ deux semaines, mon commit a été fusionné et le domaine personnalisé est fonctionnel : https://docs.lamp-ic.fr/.

Simplifiez votre documentation

En résumé, docs.page offre une solution puissante et flexible pour la gestion de votre documentation en ligne, intégrée avec GitHub. En suivant quelques étapes simples, vous pouvez rapidement mettre en place une documentation professionnelle et personnalisée.