Learn Authoring Pack pour Visual Studio Code

  • Article

Learn Authoring Pack est un ensemble d’extensions Visual Studio Code visant à simplifier la création de contenu Markdown pour Microsoft Learn. Disponible dans le VS Code Marketplace, le pack contient les extensions suivantes :

  • Learn Markdown : fournit une assistance de création Markdown pour le contenu sur Microsoft Learn, notamment la prise en charge de la syntaxe Markdown de base, ainsi que la syntaxe Markdown personnalisée comme les alertes, les extraits de code et le texte non localisable. Comprend également de l’aide de base sur la création de contenu YAML, par exemple l’insertion d’entrées de table des matières.
  • markdownlint : linter Markdown créé par David Anson et qui permet de vérifier que votre Markdown est valide.
  • Code Spell Checker : outil de vérification orthographique entièrement hors ligne de Street Side Software.
  • Learn Preview : utilise le CSS Microsoft Learn pour un aperçu Markdown plus précis, notamment pour le Markdown personnalisé.
  • Learn Article Templates : permet aux utilisateurs de créer une structure de modules Learn et d’appliquer du contenu de squelette Markdown à de nouveaux fichiers.
  • Learn YAML : fournit la validation de schéma YAML ainsi que l’autocomplétion.
  • Learn Images : fournit la compression et le redimensionnement des images pour les dossiers et les fichiers afin d’aider les auteurs de contenu Microsoft Learn.

Conditions préalables requises et hypothèses

Pour insérer des liens relatifs, des images et tout autre contenu incorporé avec l’extension Learn Markdown, la portée de votre espace de travail VS Code doit être limitée à la racine de votre dépôt Open Publishing System (OPS) cloné. Par exemple, si vous avez cloné le dépôt docs sur C:\git\SomeDocsRepo\, ouvrez ce dossier ou un sous-dossier dans VS Code : menu Fichier>Ouvrir un dossier, ou code C:\git\SomeDocsRepo\ à partir de la ligne de commande.

Certaines syntaxes Markdown prises en charge par l’extension, comme les alertes et les extraits, sont personnalisées pour OPS. Celles-ci ne s’affichent correctement que si vous les publiez par le biais d’OPS.

Comment utiliser l’extension Learn Markdown

Pour accéder au menu Learn Markdown, utilisez le raccourci Alt+M. Vous pouvez cliquer ou utiliser les flèches vers le haut et vers le bas pour sélectionner la commande souhaitée. Vous pouvez également taper pour démarrer le filtrage, puis appuyer sur Entrée quand la fonction souhaitée est mise en surbrillance dans le menu.

Pour obtenir la liste des commandes à jour, consultez le fichier Lisez-moi Learn Markdown.

Guide pratique pour générer un fichier de redirection principal

L’extension Learn Markdown comprend un script permettant de générer ou de mettre à jour un fichier de redirection principal pour un référentiel, en fonction de la métadonnée redirect_url présente dans les différents fichiers. Ce script recherche redirect_url dans chaque fichier Markdown du référentiel, ajoute les métadonnées de redirection au fichier de redirection principal (.openpublishing.redirection.json) du référentiel et déplace les fichiers redirigés dans un dossier situé à l’extérieur du référentiel. Pour exécuter le script :

  1. Sélectionnez F1 pour ouvrir la palette de commandes VS Code.
  2. Commencez à taper « Learn: Generate... ».
  3. Sélectionnez la commande Learn: Generate main redirection file.
  4. Une fois l’exécution du script terminée, les résultats de la redirection s’affichent dans le volet de sortie VS Code, et les fichiers Markdown supprimés sont ajoutés au dossier Learn Authoring\redirects sous votre chemin par défaut.
  5. Passez en revue les résultats. S’ils sont conformes à vos attentes, envoyez une demande de tirage (pull request) pour mettre à jour le dépôt.

Comment définir des raccourcis clavier

  1. Tapez Ctrl+K puis Ctrl+S pour ouvrir la liste des raccourcis clavier.

  2. Recherchez la commande pour laquelle vous souhaitez créer une combinaison de touches personnalisée, par exemple formatBold.

  3. Cliquez sur le signe plus qui apparaît près du nom de la commande quand vous pointez sur la ligne.

  4. À l’apparition d’une nouvelle zone d’entrée, tapez le raccourci clavier à associer à cette commande particulière. Par exemple, pour utiliser le raccourci courant de mise en gras, tapez Ctrl+B.

  5. Il est conseillé d’insérer une clause when dans votre combinaison de touches pour que celle-ci soit uniquement disponible dans les fichiers Markdown. Pour ce faire, ouvrez keybindings.json et insérez la ligne suivante sous le nom de la commande (veillez à ajouter une virgule entre les lignes) :

    "when": "editorTextFocus && editorLangId == 'markdown'"

    Au final, votre combinaison de touches personnalisée doit ressembler à ceci dans keybindings.json :

    [
    {
        "key": "ctrl+b",
        "command": "formatBold",
        "when": "editorTextFocus && editorLangId == 'markdown'"
    }
]

    Conseil

    Placez vos combinaisons de touches dans ce fichier pour remplacer les valeurs par défaut.

  6. Enregistrez keybindings.json.

Pour plus d’informations sur les combinaisons de touches, consultez la documentation VS Code.

Comment afficher la barre d’outils « Gauntlet » héritée

Les utilisateurs de l’ancienne extension (nom de code « Gauntlet ») remarqueront que la barre d’outils de création n’apparaît plus en bas de la fenêtre VS Code quand l’extension Learn Markdown est installée. En effet, la barre d’outils prenait une place importante sur la barre d’état de VS Code et ne suivait pas les bonnes pratiques en matière d’expérience utilisateur pour les extensions. Elle est donc dépréciée dans la nouvelle extension. Vous pouvez tout de même afficher la barre d’outils en mettant à jour votre fichier VS Code settings.json comme suit :

  1. Dans VS Code, accédez à Fichier>Préférences>Paramètres ou sélectionnez Ctrl+,.

  2. Sélectionnez Paramètres utilisateur pour changer les paramètres de tous les espaces de travail VS Code ou Paramètres de l’espace de travail pour les changer uniquement dans l’espace de travail actif.

  3. Sélectionnez Extensions>Learn Markdown Extension Configuration (Configuration de l’extension Learn Markdown), puis sélectionnez Show the legacy toolbar in the bottom status bar (Afficher la barre d’outils héritée dans la barre d’état inférieure).

    Show legacy toolbar setting in VS Code

Une fois votre sélection effectuée, VS Code met à jour le fichier settings.json. Vous êtes ensuite invité à recharger la fenêtre pour que les modifications prennent effet.

Les commandes plus récentes ajoutées à l’extension ne sont pas disponibles à partir de la barre d’outils.

Comment utiliser les modèles Learn

L’extension Learn Article Templates permet à ceux qui écrivent en VS Code d’extraire un modèle Markdown à partir d’un magasin centralisé et de l’appliquer à un fichier. Les modèles peuvent permettre de s’assurer que les métadonnées requises sont incluses dans les articles, que les normes relatives au contenu sont respectées, etc. Les modèles sont gérés en tant que fichiers Markdown dans un référentiel GitHub public.

Pour appliquer un modèle dans VS Code

  1. Vérifiez que l’extension Learn Article Templates est installée et activée.
  2. Si l’extension Learn Markdown n’est pas installée, cliquez sur F1 pour ouvrir la palette de commandes, commencez à taper « template » pour filtrer les résultats, puis cliquez sur Learn: Template. Si l’extension Learn Markdown est installée, vous pouvez utiliser la palette de commandes ou Alt+M pour afficher le menu Learn Markdown QuickPick, puis sélectionnez Template dans la liste.
  3. Sélectionnez le modèle requis dans la liste qui s’affiche.

Pour ajouter votre ID GitHub et/ou votre alias Microsoft à vos paramètres VS Code

L’extension Templates prend en charge trois champs de métadonnées dynamiques : author, ms.author et ms.date. Cela signifie que si le créateur d’un modèle utilise ces champs dans l’en-tête des métadonnées d’un modèle Markdown, ces champs seront renseignés automatiquement dans votre fichier lorsque vous appliquez le modèle, comme suit :

Champ métadonnées Valeur
author Votre alias GitHub, si spécifié dans le fichier des paramètres VS Code.
ms.author Votre alias Microsoft, si spécifié dans le fichier des paramètres VS Code. Si vous n’êtes pas un employé de Microsoft, ne renseignez pas ce champ.
ms.date La date actuelle au format pris en charge, MM/DD/YYYY. La date n’est pas automatiquement mise à jour si vous mettez à jour le fichier par la suite : vous devez la mettre à jour manuellement. Ce champ est utilisé pour indiquer « l’actualisation de l’article ».

Pour définir author et/ou ms.author

  1. Dans VS Code, accédez à Fichier>Préférences>Paramètres ou sélectionnez Ctrl+,.
  2. Sélectionnez Paramètres utilisateur pour changer les paramètres de tous les espaces de travail VS Code ou Paramètres de l’espace de travail pour les changer uniquement dans l’espace de travail actif.
  3. Dans le volet Paramètres par défaut à gauche, recherchez Learn Article Templates Extension Configuration, cliquez sur l’icône en forme de crayon en regard du paramètre requis, puis cliquez sur Remplacer dans les paramètres.
  4. Le volet Paramètres utilisateur s’ouvre à côté et contient une nouvelle entrée en bas.
  5. Ajoutez votre ID GitHub ou votre alias e-mail Microsoft, le cas échéant, et enregistrez le fichier.
  6. Vous devrez peut-être fermer et redémarrer VS Code pour que les modifications prennent effet.
  7. À présent, lorsque vous appliquez un modèle qui utilise des champs dynamiques, votre ID GitHub et/ou votre alias Microsoft sera automatiquement renseigné dans l’en-tête des métadonnées.

Pour rendre un nouveau modèle disponible dans VS Code

  1. Ébauchez votre modèle en tant que fichier Markdown.
  2. Envoyez une demande de tirage (pull request) au dossier templates du dépôt MicrosoftDocs/content-templates.

L’équipe en charge du contenu passe en revue votre modèle et fusionne la demande de tirage si elle répond aux règles de style. Une fois fusionné, le modèle est disponible pour tous les utilisateurs de l’extension Learn Article Templates.

Démonstration de plusieurs fonctionnalités

Voici une brève vidéo qui illustre les fonctionnalités suivantes de Learn Authoring Pack :

  • Fichiers YAML
    • Prise en charge de « Learn : Lien vers un fichier dans le dépôt »
  • Fichiers Markdown
    • Option de menu contextuel permettant de mettre à jour la valeur de la métadonnée « ms.date »
    • Prise en charge de l’autocomplétion du code pour les identificateurs de langage de délimitation de code
    • Avertissements d’identificateur de langage de délimitation de code non reconnu / prise en charge de la correction automatique
    • Trier la sélection par ordre croissant (de A à Z)
    • Trier la sélection par ordre décroissant (Z à A)

Étapes suivantes

Explorez les diverses fonctionnalités disponibles dans l’extension Learn Authoring Pack pour Visual Studio Code.