GitHub : mise en page avec Markdown

Lorsque vous documentez votre projet GitHub, vous n'êtes pas obligé de vous contenter d'un simple texte courant uniforme. Avec le Markdown, en partie maison, les fichiers Liesmich et la documentation se mettent vraiment en page.

  • Qu'est-ce que le Markdown?
  • Titres et balises
  • Liens et images
  • Listes et tableaux
  • Emojis et autres

Qu'est-ce que le Markdown?

Markdown est en fait une chose assez simple, un langage de balisage. Tout comme HTML : HTML était autrefois un moyen "simple" de concevoir des pages web - simple par rapport aux langages de programmation. Mais en fin de compte, la syntaxe HTML n'est pas adaptée aux longs textes courants. Des parenthèses, des guillemets et certains mots-clés attendent constamment d'être placés au caractère près. Si vous voulez par exemple écrire le mot "gras" en gras : gras

Markdown simplifie nettement les choses, un simple **gras** est affiché sur les pages compatibles Markdown de la même manière que la variante HTML. Plus précisément : il est traduit dans la variante HTML. Les balises Markdown sont nettement plus faciles à mémoriser et surtout à taper.

Il n'existe pas qu'une seule version de Markdown, même si la plupart des éléments sont standardisés. Github offre en tout cas quelques possibilités spéciales en plus, par exemple pour pouvoir mentionner les utilisateurs Github avec un formatage mis en évidence ou pour présenter clairement le code et les commandes.

Ci-dessous, vous verrez quels éléments utiliser et comment les utiliser pour créer un fichier readme joliment formaté :

  • Überschriften
  • Textauszeichnung (fett, kursiv, durchgestrichen)
  • Links
  • Bilder
  • Listen (ungeordnet, nummeriert, ToDo)
  • Tabellen
  • Emojis

Außen vor bleiben Referenzen auf Nutzer (@nutzer) und Pull Requests, da diese in normalen Dateien nicht funktionieren, sondern nur in Beschreibungen und Kommentaren von Pull Requests und Issues.

Überschriften und Auszeichnungen

Wenn Sie in GitHub ein Projekt anlegen, bekommen Sie auch gleich eine vorgefertigte, leere Datei "LIESMICH.md" - wobei das "md" natürlich für Markdown steht. Öffnen Sie den Editor für die Datei und beginnen Sie zum Beispiel mit den Überschriften, um den Artikel zu strukturieren:

# Mein Projekt
## Installation