mdBook : renommage d’une page mdBook

Si nous utilisons mdbook serve, voir le chapitre de page mdBook Consignes pour mdbook serve (dans cette même page) AVANT de lire ce qui suit.

Je recommande de faire une sauvegarde du dossier source avant de commencer une opération de ce type au moins les premières fois avant d’être sûr·e de bien maîtriser le sujet.

De même, je recommande de désactiver mdbook serve le temps d’avoir fait le tour de la question jusqu’à bien maîtriser le processus lorsque nous souhaitons effectuer des opérations de refactorisation (refactoring) de nos codes sources de projet mdBook.

Consignes sans mdbook serve

Si nous nous apercevons que nous souhaitons changer le titre d’une page mdBook, il nous faut :

• changer le nom du fichier.md ;
• Dans le fichier SUMMARY.md :
  • Changer le titre entre [] (si nécessaire pour qu’il corresponde au nouveau nom du fichier.md) ;
  • Changer le nom du fichier.md dans le lien entre () pour qu’il corresponde bien au nouveau nom de fichier.md.
• ouvrir le fichier.md sous son nouveau nom pour changer le titre précédé d’un # du début afin de le faire correspondre au (nouveau) titre figurant dans le sommaire mdBook.
• rechercher les éventuels liens vers fichier.md dans les autres fichiers du projet mdBook pour les mettre à jour avec le nouveau nom du fichier.md.
• enregistrer tous les fichiers ainsi modifiés.
• faire un mdbook build pour
• vérifier que tout se passe bien :
  • ouvrir le sommaire mdBook du site Web mdBook et vérifier son contenu affiché ;
  • cliquer sur le lien de la page mdBook pour nous assurer qu’il nous mène bien à la page souhaitée ;
  • contrôler la liste des fichiers dans le dossier source : il peut arriver que le compilateur mdBook recrée un fichier avec l’ancien nom de fichier.md;
  • Si un fichier portant l’ancien nom de fichier.md réapparaît, c’est qu’il existe un lien vers celui-ci quelque-part dans notre projet mdBook.
    Il nous faut alors
    • trouver ce lien,
    • corriger le lien,
    • supprimer le fichier.md avec l’ancien nom que le compilateur mdBook a créé,
    • relancer un mdbook build puis reprendre à l’étape contrôler la liste des fichiers dans le dossier source.
  • faire une recherche pour nous assurer qu’aucun lien vers l’ancien nom de fichier.md n’existe dans le projet mdBook.

Cette procédure vaut pour un déplacement de fichier même sans modification du nom de fichier ni du titre associé.

Un seul à la fois

Je recommande de ne changer qu’un seul nom de page mdBook à la fois et de prendre le temps de bien vérifier avant de procéder à d’autres changements de noms de pages mdBook.

Consignes pour mdbook serve

Si mdbook serve est en fonctionnement, comme celui-ci vérifie la liste des fichiers.md en boucle en permanence :

• si nous enregistrons SUMMARY.md dans sa nouvelle version sans avoir renommé le fichier.md, mdbook serve crée le nouveau fichier, à côté de l’ancien que nous n’avons pas encore renommé ;
• si nous commençons par renommer le fichier.md, mdbook serve recrée le fichier sous l’ancien nom à côté du fichier que nous venons de renommer.

En principe, la procédure proposée dans Consignes sans mdbook serve, si elle est réalisée dans l’ordre proposé, fonctionne sans avoir besoin d’interrompre mdbook serve.

Toutefois, je recommande de désactiver mdbook serve le temps d’avoir fait le tour de la question jusqu’à bien maîtriser le processus.

Caractères autorisés

Pour connaître les caractères autorisés pour le nommage des sous-dossiers et des fichiers.md, voir mdBook : Caractères autorisés.