Structure de fichiers et de dossiers Wiki dans Git

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022

Cet article décrit les fichiers et la structure des dossiers pour les wikis préconfigurés et ceux publiés en tant que code. Pour les deux types de wiki, les fichiers sont stockés dans un dépôt Git. Les fichiers peuvent inclure des pages Markdown, du code, des images, des pièces jointes ou d’autres artefacts. Pour établir la séquence de présentation des fichiers, Git ajoute un fichier spécial (.order) dans chaque dossier de dépôt.

Lorsque vous créez un projet, un wiki n’est pas créé par défaut. Vous pouvez approvisionner un wiki, créer un fichier README ou publier du code de projet en tant que wiki.

Vous créez votre wiki à l’aide de l’interface utilisateur Azure DevOps. Vous pouvez ensuite modifier le wiki à partir de votre chemin d’URL de dépôt Git.

Fichiers de référentiel et structure de dossiers

Le dépôt Git d’un wiki a deux conventions d’affectation de noms :

• Le nom du dépôt wiki est <ProjectName>.wiki où <ProjectName> est le nom de votre projet.
• Le nom de la branche racine du dépôt wiki est wikiMain.

Vous gérez un dépôt wiki de la même façon que vous gérez d’autres dépôts Git en définissant des stratégies de branche sur la wikiMain branche. Vous pouvez également apporter des modifications à votre branche locale wikiMain et les envoyer directement à la branche distante sans définir de stratégies.

Un dépôt wiki se compose des fichiers et dossiers suivants :

• Fichier pour chaque page Markdown située au niveau racine
• Un fichier nommé .order situé au niveau racine et également dans chaque sous-dossier
• Sous-dossier pour chaque page wiki qui a des sous-pages
• Dossier nommé .attachments pour stocker toutes les pièces jointes utilisées dans le wiki

Conventions d’affectation de noms de fichiers

Le nom de fichier de chaque page wiki correspond au titre de la page wiki. Dans le nom du fichier, un trait d’union (-) représente un espace dans le titre de la page. Par exemple, le titre de la page « Comment contribuer » correspond au nom de fichier How-to-contribute.md. Le chemin d’URL de la page wiki inclut le nom du fichier. Par exemple : https://github.com/ExampleWiki/How-To/How-to-contribute.md. Cette approche permet de garantir que les liens de signet vers la page restent intacts, car le wiki change au fil du temps.

Chaque page wiki correspond à un fichier dans le référentiel Git wiki. Les restrictions suivantes s’appliquent aux noms de fichiers de page et à la taille de fichier :

• Nom du fichier : lorsque vous choisissez un nom pour le fichier de page, n’oubliez pas que le chemin complet du fichier doit comporter 235 caractères ou moins. Le chemin complet de la page se compose de l’URL du dépôt, du chemin d’accès du dossier au fichier de page et du nom du fichier de page. Par exemple : https://github.com/ExampleWiki/Contributors/Code/How-to-add-code-to-the-project.md.

• Unicité : le nom du fichier de page doit être unique dans son emplacement de dossier dans la hiérarchie du référentiel wiki. Le nom est sensible à la casse.

• Caractères spéciaux : le nom du fichier de page a des restrictions sur les caractères spéciaux suivants :

  • Aucun caractère de contrôle Unicode ni caractères de substitution
  • Aucun caractère imprimable : barre oblique /, barre oblique inverse \, hachage #
  • Aucun symbole de point . au début ou à la fin du nom

• Taille du fichier : la taille maximale du fichier de page est de 18 Mo.

• Taille du fichier de pièce jointe : la taille maximale de toute pièce jointe à un fichier de page est de 19 Mo.

Caractères spéciaux autorisés

Plusieurs caractères spéciaux sont autorisés dans un nom de fichier de page, tels que le signe deux-points : et le trait d’union -. Par exemple, vous pouvez nommer un fichier Markdown en tant que FAQ :0525 ou Setup-Guide.

Le tableau suivant répertorie les caractères spéciaux autorisés dans les noms de fichiers de page wiki et la chaîne encodée d’URI correspondante :

Par exemple, le nom de fichier FAQ :0525 est encodé en tant que FAQ%3A0525.

Séquence de pages et fichier .order

Le fichier .order définit la séquence de pages wiki. Git recherche ce fichier dans chaque dossier pour identifier la séquence de présentation des fichiers à cet emplacement. La séquence de pages par défaut est l’ordre alphabétique (A à Z) par nom de fichier.

|- parent-folder
|-- sub-folder1
|   |-- file1.md
|   |-- file2.md
|-- sub-folder2
|   |-- file3.md
|   |-- file4.md
|-- .order

Définir une séquence de pages personnalisée

Lorsqu’un dossier n’a pas de fichier .order , Git utilise la séquence alphabétique par défaut.

Vous pouvez définir une séquence personnalisée pour n’importe quel dossier en mettant à jour le fichier .order dans le dossier, y compris au niveau racine.

Le visuel suivant montre un exemple de table des matières wiki (TOC) et du fichier .order correspondant qui crée la table des matières.

Le fichier .order remplace la séquence par ordre alphabétique par « Marketing » suivie de « Fabrikam Fiber ».

Pour plus d’informations sur la réorganisation des pages wiki, consultez Ajouter, modifier et réorganiser des pages wiki.

Restaurer une séquence alphabétique

Si un dossier a une séquence personnalisée, vous pouvez rétablir la méthode de tri par ordre alphabétique en procédant comme suit :

1. Copiez l’URL de clone du wiki et ouvrez-la dans un navigateur. Le dépôt Git pour le wiki s’ouvre.

2. Accédez au fichier .order que vous souhaitez remettre à l'état précédent puis supprimez le fichier. Une fois le fichier supprimé, Git crée automatiquement un fichier .order pour cet emplacement. Le nouveau fichier utilise la séquence par défaut.

Contenu connexe

• Configurer le wiki et publier du code en tant que wiki
• Créer un wiki pour votre projet d’équipe
• Publier un dépôt Git sur un wiki