VSO : welcome page et markdown

Depuis août 2014, Microsoft a introduit le concept de page d’accueil à un team project dans VSO. Je vous propose, dans ce billet, de voir l’intérêt de la fonctionnalité et de faire un petit tour de ce qu’il est possible de faire.

Pourquoi une welcome page ?

Depuis l’introduction du nouveau portail web à TFS 2012, la page d’accueil permet d’afficher des informations relatives à l’avancement du développement du projet via le résumé du sprint en cours, le burndown chart et les différents titles ou graphiques renvoyant vers des requêtes sur vos work items. Toutefois, il n’existait pas de moyen intégré pour afficher simplement des informations sur le projet aux nouveaux menus tels que la description du projet, la structure des sources, les builds, la documentation… C’est donc pour combler ce manque qu’a été rajouté la welcome page juste à côté de la page d’accueil existante 🙂

Welcome page

Lorsque l’on clique sur le lien, on aura droit, la première fois, à une page standard indiquant les différentes options pour commencer.

Le principe est simple, il suffit que VSO trouve à la racine du contrôleur de sources un fichier readme.md pour l’afficher comme welcome page 🙂

Avant décembre 2014, il fallait donc créer localement un fichier readme.md et l’archiver afin qu’il soit pris en compte par le portail. Depuis décembre, Microsoft a déployé une nouvelle fonctionnalité permettant d’éditer directement en ligne un fichier et a mis à jour les welcome page afin de permettre non seulement l’édition en ligne mais aussi la création directement depuis l’interface web.

Il est à noter que la navigation sur la partie gauche ne se comporte pas de la même manière si l’on a un contrôleur de sources Git ou TFVC. Pour les projets TFVC, on ne voit maintenant plus qu’une entrée renvoyant vers le fichier readme.md (avant la mise à jour de décembre on voyait l’ensemble des fichiers .md se trouvant à la racine). Pour les projets Git, on retrouvera une entrée pour chaque repository que l’on aura créé, chaque entrée renvoyant vers le fichier readme.md du repository. Il faut espérer que Microsoft améliore cette partie afin d’offrir la possibilité de personnaliser son menu.

Pour la mise en page Microsoft est parti sur un standard : le markdown avec support des extensions GitHub. Le markdown permet de formater simplement du texte, l’ajout de balise simple qui peut ensuite être converti en HTML par exemple.

Edition d’une page

Les bases

Si vous n’avez pas déjà de fichier .md, la façon la plus simple d’éditer vos pages est de passer par l’éditeur en ligne. Pour cela, rien de plus simple, il suffit de cliquer sur le bouton Edit en haut de la page pour voir le code markdown 🙂

La page en mode édition va contenir une barre d’action et le contenu pour édition :

La barre d’action permet de :

• saisir le commentaire du commit
• faire un commit
• annuler les modifications
• prévisualiser les modifications au format HTML
• faire une comparaison du fichier par rapport à la dernière version

Le contenu est à éditer au texte simple en y ajoutant les marqueurs pour le formatage markdown. Je ne vais pas vous expliquer ici l’ensemble des marqueurs markdown, mais si vous ne connaissez pas vous pouvez lire les deux pages suivantes :

• Syntaxe standard : https://help.github.com/articles/markdown-basics/
• Syntaxe étendue GitHub : https://help.github.com/articles/github-flavored-markdown/

Voici par contre quelques informations pour créer des liens vers d’autres éléments 🙂

Liens vers des pages

En markdown un lien a la syntaxe suivante :

[texte à afficher](lien)

Lorsque l’on veut faire un lien vers une page dans le contrôleur de sources, on peut utiliser la syntaxe suivante :

• Chemin relatif :

  [texte](./page.md)

• Chemin absolu Git :

  [texte](/repertoire/page.md)

• Chemin absolu Tfvc :

  [texte]($/projet/repertoire/page.md)

Avec Tfvc, il est donc possible de faire des liens inter-projets en utilisant des chemin absolus. Pour les repos Git, il faudra, par contre, utiliser l’URL publique du fichier.

Liens vers des entêtes

Il est possible de faire des liens vers les différentes entêtes d’une page. La syntaxe est la suivante :

[texte](#identifiant de l'entête)

Chaque entête se voit attribué automatiquement un identifiant qui correspond à son texte avec les espaces et autres caractères accentués remplacés par des tirets.

Par exemple : “Ma super entête” aura pour id “ma-super-ent-te” et pourra être liée via

[texte](#ma-super-ent-te)

Il est aussi possible de faire un lien vers une entête d’un autre fichier via la syntaxe :

[texte](<chemin de la page>#<id de l'entete>)

Insérer une image

Pour insérer une image, on utilisera la syntaxe :

![texte alternatif](<chemin de l'image>)

Le chemin de l’image peut être un chemin relatif ou absolu dans le contrôleur de source Git ou Tfvc ou vers une URL externe.

Créer une page

Pour créer une page, il suffit soit de commit la page et d’ajouter un lien vers celle-ci, soit de créer un lien vers la page et lorsque l’on cliquera sur le lien VSO proposera de la créer.

Conclusion

Voilà pour ce petit tour d’horizon de la welcome page. S’il fallait résumer, on peut supposer qu’il s’agit d’un premier pas pour intégrer une notion de wiki dans VSO 🙂