Éditeur en ligne GitLab et Markdown#

Danger

La présente page est un travail en cours !

L’éditeur en ligne intégré à GitLab est donc une version Web et light de l’éditeur Visual Studio Code. Ce dernier fournit de puissantes fonctionnalités :

  • d’édition en général ;

  • d’édition de fichiers Markdown en particulier.

Nous les présentons ici car elles vous feront gagner du temps si vous contribuez au contenu de la présente FAQ.

Note

Pour vous aider à commencer à éditer des fichiers Markdown, vous pouvez utiliser le modèle de profil Doc Writer pour installer des extensions utiles (vérificateur d’orthographe, linter Markdown) et configurer paramètres appropriés.

Danger

Ceci ne semble pas possible avec l’éditeur en ligne GitLab.

1.  Édition Markdown#

1.1.  Structure du document#

La vue « Outline » (« Structure ») est une section distincte dans la partie inférieure de l’explorateur de fichiers. Lorsqu’elle est développée, elle affiche la structure (la table des matières) créée à partir des rubriques du fichier Markdown en cours.

Aperçu Markdown Aperçu Markdown

La vue « Outline » est un excellent moyen d’examiner le plan de votre document.

1.2.  Fragments de code pour Markdown#

L’éditeur en ligne comprend des extraits utiles qui peuvent accélérer l’écriture de textes en Markdown. Cela inclut des fragments pour les blocs de code, les images, et plus encore. Appuyez sur Ctrl+Espace (Trigger Suggest) pendant l’édition pour voir une liste de fragments Markdown suggérés. Vous pouvez également utiliser le sélecteur de fragments dédié en sélectionnant Insert Snippet dans la palette de commandes.

1.3.  Atteindre une rubrique du fichier#

Utilisez Ctrl+Shift+O ou ou Ctrl+P @ pour atteindre rapidement une rubrique du fichier en cours.

Atteindre une rubrique dans un fichierMarkdown

Vous pouvez parcourir toutes les rubriques du fichier ou commencer à taper un titre de rubrique pour trouver celui que vous cherchez. Une fois que vous avez trouvé la rubrique que vous voulez, appuyez sur Entrée pour déplacer votre curseur jusqu’à lui. Appuyez sur Échap pour annuler le saut vers la rubrique.

1.4.  Atteindre une rubrique de l’espace de travail#

Utilisez Ctrl+T ou Ctrl+P # pour rechercher les rubriques dans tous les fichiers Markdown de l’espace de travail en cours.

Atteindre une rubrique dans tous les fichiers Markdown d'un espace de travail

Commencez à taper un titre de rubrique pour filtrer la liste et trouver la rubrique que vous recherchez.

1.5.  Complétions de chemins#

Les complétions de chemins permettent de créer des liens vers des fichiers et des images. Ces chemins sont affichés automatiquement lorsque vous tapez le chemin d’une image ou d’un lien, et peuvent également être demandés manuellement en utilisant Ctrl+Espace.

Complétions de chemin dans un lienMarkdown

Les chemins commençant par / sont résolus par rapport à la racine de l’espace de travail actuel, tandis que les chemins commençant par ./ ou sans préfixe sont résolus par rapport au fichier actuel. Il est aussi possible de visiter les réperoires parents au moyen de ../. Les suggestions de chemin sont automatiquement affichées lorsque vous tapez / ou peuvent être invoquées manuellement en utilisant Ctrl+Espace.

Les complétions de chemins peuvent aussi vous aider à relier des rubriques au sein du fichier courant ou dans un autre fichier Markdown. Commencez le chemin par # pour voir les complétions pour tous les rubriques dans le fichier (selon le paramétrage, vous devrez peut-être utiliser Ctrl+Espace pour les voir) :

Suggestions de sections de rubrique dans un lienMarkdown

1.6.  Créer des liens vers une rubrique dans un autre fichier#

Danger

Ceci semble ne pas fonctionner dans l’éditeur en ligne GitLab.

Vous avez besoin de créer un lien vers une rubrique dans un autre document Markdown, mais vous ne vous souvenez pas ou ne voulez pas taper le chemin complet du fichier ? Essayez d’utiliser les complétions de rubrique de l’espace de travail ! Pour commencer, il suffit de taper ## dans un lien Markdown pour obtenir une liste de tous les rubriques Markdown de l’espace de travail actuel :

Suggestions pour tous les rubriques Markdown de l'espace de travailactuel

Acceptez l’une de ces complétions pour insérer le lien complet vers cette rubrique, même s’il se trouve dans un autre fichier :

Ajouter un lien vers la rubrique sélectionné dans un autrefichier

Vous pouvez configurer si/quand les complétions de la rubrique de l’espace de travail s’affichent avec le paramètre markdown.suggest.paths.includeWorkspaceHeaderCompletions. Les valeurs valides sont :

  • onDoubleHash (par défaut) - Affiche les complétions de la rubrique de l’espace de travail seulement après que vous ayez tapé ##.

  • onSingleOrDoubleHash - Affiche les complétions de la rubrique de l’espace de travail après que vous ayez tapé # ou ##.

  • never - Ne jamais afficher les complétions de rubrique de l’espace de travail.

Gardez à l’esprit que la recherche de tous les rubriques dans l’espace de travail actuel peut être coûteuse, il peut donc y avoir un léger retard la première fois qu’ils sont demandés, en particulier pour les espaces de travail avec beaucoup de fichiers Markdown.

1.7.  Insérer des images et des liens vers des fichiers#

En plus de la complétion de chemin, l’éditeur en ligne supporte également quelques autres façons d’insérer des images et des liens vers des fichiers dans vos documents Markdown.

Vous pouvez glisser-déposer un fichier depuis l’explorateur de l’éditeur en ligne ou depuis votre système d’exploitation dans l’éditeur.

Commencez par faire glisser un fichier depuis l’explorateur de l’éditeur en ligne sur votre code Markdown, puis maintenez enfoncé Shift pour commencer à le déposer dans le fichier. Le curseur de prévisualisation montre l’endroit où il sera inséré lorsque vous le déposez.

Insertion d'un lien Markdown par glisser-déposer depuisl'explorateur

Si vous préférez utiliser le clavier, vous pouvez également copier et coller un fichier ou une image dans un éditeur Markdown.

Danger

Le copier-coller d’images semble ne pas fonctionner dans l’éditeur en ligne GitLab.

Vous pouvez également utiliser la commande Markdown : Insérer une image à partir de l’espace de travail pour insérer des images et Markdown : Insérer un lien vers un fichier dans l’espace de travail pour insérer des liens vers des fichiers.

Danger

Ces commandes semblent introuvables dans l’éditeur en ligne GitLab.

Les images insérées utilisent la syntaxe d’image Markdown ![](path/to/image.png). Les liens insèrent un lien Markdown normal [](path/to/file.md).

1.8.  Sélection intelligente#

La sélection intelligente vous permet d’étendre et de réduire rapidement la sélection dans les documents Markdown. Cela peut être utilisé pour sélectionner rapidement des éléments de bloc entiers (tels que des codes ou des tableaux) et pour sélectionner tout le contenu d’une section de rubrique dans le fichier Markdown.

La sélection intelligente utilise les commandes suivantes :

Développer:

Shift+Alt+Right

Réduire:

Shift+Alt+Left

La sélection s’applique aux éléments suivants et suit un modèle hiérarchique traditionnel :

  • rubriques ;

  • listes ;

  • blocs de guillemets ;

  • blocs de code clôturés ;

  • blocs de code html ;

  • paragraphes.

La sélection intelligente dans un document Markdown s'étend d'un élément debloc à l'élément de bloc qui le contient, au reste du contenu sous une rubrique,à la rubrique lui-même

1.9.  Validation des liens#

Danger

La validation des liens semble ne pas fonctionner dans l’éditeur en ligne GitLab.

La validation des liens vérifie les liens locaux dans votre code Markdown pour s’assurer qu’ils sont valides. Cela permet de détecter des erreurs courantes, telles que l’établissement d’un lien vers une rubrique qui a été renommé ou vers un fichier qui n’existe plus sur le disque.

Avertissement affiché dans l'éditeur en cas de lien vers un fichier quin'existe pas

La validation des liens est désactivée par défaut. Pour l’activer, il suffit de définir "markdown.validate.enabled": true : l’éditeur en ligne analysera alors les liens Markdown vers les rubriques, les images et les autres fichiers locaux. Les liens invalides seront signalés comme des avertissements ou des erreurs. Toute la validation des liens se fait localement et il n’y a pas de vérification des liens http(s) externes.

Il y a quelques paramètres que vous pouvez utiliser pour personnaliser la validation des liens :

  • markdown.validate.fileLinks.enabled - Active/désactive la validation des liens vers les fichiers locaux : [link](/path/to/file.md)

  • markdown.validate.fragmentLinks.enabled - Active/désactive la validation des liens vers les rubriques du fichier courant : [link](#some-header)

  • markdown.validate.fileLinks.markdownFragmentLinks - Active/désactive la validation des liens vers les rubriques de l’autre fichier markdown : [link](other-file.md#some-header)

  • markdown.validate.referenceLinks.enabled - Active/désactive la validation des liens de référence : [link][ref].

  • markdown.validate.ignoredLinks - Une liste de globs de liens qui ne sont pas validés. Ceci est utile si vous créez des liens vers des fichiers qui n’existent pas sur le disque mais qui existent une fois que le texte Markdown a été publié.

1.10.  Trouver toutes les références aux rubriques et aux liens#

Utilisez la commande Find All References (Shift+Alt+F12) pour trouver tous les emplacements dans l’espace de travail actuel où une rubrique ou un lien Markdown est référencé :

Sauter à une rubrique dans un fichier Markdown

La commande Find All References est supportée pour :

  • rubriques : # Ma rubrique. Affiche tous les liens vers #ma-rubrique ;

  • liens externes : [texte](https://example.com). Affiche tous les liens vers https://example.com ;

  • liens internes : [text](./path/to/file.md). Affiche tous les liens vers ./path/to/file.md ;

  • fragments dans les liens : [text](./path/to/file.md#my-header). Affiche tous les liens vers #ma-rubrique dans ./chemin/vers/fichier.md.

1.11.  Renommer les rubriques et les liens#

Vous en avez assez de briser accidentellement des liens lorsque vous changez une rubrique Markdown ? Essayez d’utiliser Renommer le symbole (F2) à la place. Après avoir tapé le nouveau nom de la rubrique et appuyé sur Entrée, l’éditeur en ligne mettra à jour la rubrique ainsi que tous les liens vers cette rubrique :

Renommer une rubrique Markdown pour mettre à jour tous les liens verslui

Vous pouvez aussi utiliser F2 sur :

  • rubriques : # Ma rubrique. Cela mettra à jour tous les liens vers #ma-rubrique.

  • Les liens externes : [texte](http://example.com/page). Ceci mettra à jour tous les endroits qui ont un lien vers http://example.com/page

  • Liens internes : [text](./path/to/file.md). Cela renommera le fichier ./path/to/file.md et mettra à jour tous les liens vers ce fichier.

  • Fragments dans les liens : [text](./path/to/file.md#my-header). Cela renommera la rubrique dans ./path/to/file.md et mettra également à jour tous les liens vers lui.

1.12.  Mise à jour automatique des liens lors d’un déplacement ou d’un renommage de fichier#

Avec la mise à jour automatique des liens Markdown, l’éditeur en ligne mettra automatiquement à jour les liens Markdown chaque fois qu’un fichier lié est déplacé ou renommé. Vous pouvez activer cette fonctionnalité avec le paramètre markdown.updateLinksOnFileMove.enabled. Les valeurs valides sont :

  • never (par défaut) - Ne pas essayer de mettre à jour les liens automatiquement.

  • prompt - Confirmer avant de mettre à jour les liens.

  • always - Mettre à jour les liens automatiquement sans confirmation.

La mise à jour automatique des liens détecte les renommages des fichiers Markdown, des images et des répertoires. Vous pouvez l’activer pour d’autres types de fichiers avec markdown.updateLinksOnFileMove.include.

2.  Aperçu Markdown#

L’éditeur en ligne supporte les fichiers Markdown dès le départ. Il suffit de commencer à écrire du texte Markdown, de sauvegarder le fichier avec l’extension .md et de basculer la visualisation de l’éditeur entre le code et la prévisualisation du fichier Markdown ; évidemment, vous pouvez aussi ouvrir un fichier Markdown existant et commencer à travailler avec lui. Pour passer d’une vue à l’autre, appuyez sur Ctrl+Shift+V dans l’éditeur. Vous pouvez voir l’aperçu côte à côte (Ctrl+K V) avec le fichier que vous éditez et voir les changements reflétés en temps réel au fur et à mesure que vous éditez.

Voici un exemple avec un fichier simple.

Aperçu Markdown

**Vous pouvez également faire un clic droit sur l’onglet de l’éditeur et sélectionner Ouvrir un aperçu (Ctrl+Shift+V) ou utiliser la Palette de commandes (Ctrl+Shift+P) pour exécuter la commande Markdown : Ouvrir l’aperçu sur le côté (Ctrl+K V).

2.1.  Prévisualisations dynamiques et verrouillage des prévisualisations#

Par défaut, les aperçus Markdown sont automatiquement mis à jour pour afficher l’aperçu du fichier Markdown actuellement actif :

L'aperçu bascule automatiquement pour afficher le document Markdown encours

Vous pouvez verrouiller un aperçu Markdown en utilisant la commande Markdown : Toggle Preview Locking pour la verrouiller sur le document Markdown en cours. Les aperçus verrouillés sont indiqués par [Aperçu] dans le titre :

Un aperçu Markdownverrouillé

Note: La commande Markdown : Toggle Preview Locking n’est disponible que si la prévisualisation Markdown est l’onglet actif.

2.2.  Synchronisation de l’éditeur et de l’aperçu#

L’éditeur en ligne synchronise automatiquement l’éditeur Markdown et les panneaux de prévisualisation. Si vous faites défiler l’aperçu Markdown, l’éditeur défile pour s’adapter à l’affichage de l’aperçu. Faites défiler l’éditeur Markdown et la prévisualisation s’adapte à sa fenêtre :

Synchronisation du défilement de la sélection de l'éditeur de l'aperçuMarkdown

Vous pouvez désactiver la synchronisation du défilement en utilisant les paramètres markdown.preview.scrollPreviewWithEditor et markdown.preview.scrollEditorWithPreview (/docs/getstarted/settings.md).

La ligne actuellement sélectionnée dans l’éditeur est indiquée dans l’aperçu Markdown par une barre gris clair dans la marge gauche :

Marqueur de ligne de l'éditeur dans l'aperçuMarkdown

En outre, un double clic sur un élément dans l’aperçu Markdown ouvrira automatiquement l’éditeur pour le fichier et fera défiler jusqu’à la ligne la plus proche de l’élément cliqué.

Un double clic sur l'aperçu Markdown bascule versl'éditeur

3.  Extension de l’aperçu Markdown#

Les extensions peuvent ajouter des styles et des scripts personnalisés à l’aperçu Markdown pour changer son apparence et ajouter de nouvelles fonctionnalités.

Danger

Les extensions VSCode ne peuvent actuellement pas être installées dans l’éditeur en ligne GitLab.

3.1.  Utiliser votre propre CSS#

Vous pouvez également utiliser votre propre CSS dans l’aperçu Markdown avec le "markdown.styles": [] paramètre. Ceci répertorie les URL pour que les feuilles de style soient chargées dans l’aperçu Markdown. Ces feuilles de style peuvent soit être des URL « https » ou des chemins relatifs vers des fichiers locaux dans l’espace de travail actuel.

Par exemple, pour charger une feuille de style appelée « Style.css » à la racine de votre fichier actuel espace de travail, utilisez Fichier → Préférences → Paramètres pour afficher le fichier settings.json de l’espace de travail et effectuez cette mise à jour :

// Placez vos paramètres dans ce fichier pour écraser les paramètres par défaut et utilisateur.
{
     "markdown.styles": [
         "Style.css"
     ]
}

3.2.  Gardez les espaces à la fin afin de créer des sauts de ligne#

Pour créer des sauts de ligne, Markdown nécessite deux espaces ou plus à la fin d’une ligne. Selon les paramètres de votre utilisateur ou de votre espace de travail, l’éditeur en ligne peut être configuré pour supprimer les espaces de fin de ligne. Afin de conserver les espaces de fin de ligne uniquement dans les fichiers Markdown, vous pouvez ajouter ces lignes à votre settings.json :

{
  "[markdown]": {
    "files.trimTrailingWhitespace": false
  }
}

4.  Sécurité de l’aperçu Markdown#

Pour des raisons de sécurité, l’éditeur en ligne restreint le contenu affiché dans l’aperçu Markdown. Cela inclut la désactivation de l’exécution des scripts et l’autorisation de charger des ressources uniquement via https.

Lorsque l’aperçu Markdown bloque le contenu d’une page, une fenêtre d’alerte s’affiche dans le coin supérieur droit de la fenêtre d’aperçu :

Alerte de sécurité Markdown

Vous pouvez modifier le contenu autorisé dans l’aperçu Markdown en cliquant sur cette fenêtre contextuelle ou en exécutant la commande Markdown : Modifier les paramètres de sécurité de l’aperçu dans n’importe quel fichier Markdown :

Sélecteur de sécurité Markdown

Les paramètres de sécurité de l’aperçu Markdown s’appliquent à tous les fichiers de l’espace de travail.

Voici les détails de chacun de ces niveaux de sécurité :

4.1.  Strict#

Il s’agit du paramètre par défaut. Ne charge que du contenu fiable et désactive l’exécution des scripts. Bloque les images http.

Il est fortement recommandé de garder la sécurité Strict activée à moins que vous n’ayez une très bonne raison de la changer ET que vous fassiez confiance à tous les fichiers Markdown dans l’espace de travail.

4.2.  Autoriser le contenu non sécurisé#

Maintient les scripts désactivés mais permet au contenu d’être chargé via http.

4.3.  Désactiver#

Désactive la sécurité supplémentaire dans la fenêtre de prévisualisation. Cela permet l’exécution de scripts et autorise également le chargement de contenu via http.

5.  Doc Writer profile template#

Les Profils vous permettent de changer rapidement vos extensions, vos paramètres et la présentation de l’interface utilisateur en fonction de votre projet ou de votre tâche en cours. Pour vous aider à démarrer avec l’édition de Markdown, vous pouvez utiliser le modèle de profil Doc Writer, qui est un profil curaté avec des extensions et des paramètres utiles. Vous pouvez utiliser un modèle de profil tel quel ou l’utiliser comme point de départ pour le personnaliser davantage en fonction de vos propres flux de travail.

You select a profile template through the Profiles > Create Profile… dropdown:

Create Profile dropdown with profiletemplates

Once you select a profile template, you can review the settings and extensions, and remove individual items if you don’t want to include them in your new Profile. After creating the new profile based on a template, changes made to settings, extensions, or UI are persisted in your profile.

6.  Markdown extensions#

In addition to the functionality l’éditeur en ligne provides out of the box, you can install an extension for greater functionality.

Tip: Select an extension tile above to read the description and reviews to decide which extension is best for you. See more in the Marketplace.

7.  Next steps#

Read on to find out about:

  • CSS, SCSS, et Less - Vous voulez éditer votre CSS ? l’éditeur en ligne offre une excellente prise en charge de l’édition CSS, SCSS et Less.

8.  Questions courantes#

8.1.  Y a-t-il un correcteur orthographique ?#

Il n’est pas installé avec l’éditeur en ligne mais il existe des extensions de correction orthographique. Consultez le [l’éditeur en ligne Marketplace] (https://marketplace.visualstudio.com/vscode) pour trouver des extensions utiles qui vous aideront dans votre travail.

8.2.  L’éditeur en ligne supporte-t-il le GitHub Flavored Markdown ?#

Non, l’éditeur en ligne cible la spécification Markdown CommonMark en utilisant la bibliothèque markdown-it. GitHub s’oriente vers la spécification CommonMark, ce que vous pouvez lire dans cette mise à jour.

Sources

https://code.visualstudio.com/docs/languages/markdown