Récapitulatif de ce qu'il faut savoir sur Kramdown (Markdown) avec Jekyll

Table des matières

Ce document réalise une synthèse sur l'utilisation de kramdown avec Jekyll.

1 Markdown et Kramdown

Markdown
C'est un outil de conversion de texte en HTML. Il définit une syntaxe simple qui permet de structurer son document.
kramdown
C'est une surcouche à Markdown, qui rajoute de légères améliorations. C'est la syntaxe kramdown qui est utilisée par défaut pour les fichiers .md dans Jekyll.

Dans ce qui suit, la syntaxe utilisée est celle de Markdown, qui se retrouve dans kramdown. Les ajouts de kramdown sont répertoriés (liste non exhaustive) dans la rubrique 10.

2 Les titres

Les titres permettent de structurer le document. On utilise # pour signifier un titre. Selon le nombre, il sera plus ou moins important.

# Voici un titre de niveau important
## Là, c'est un titre un peu moins important 
### Et ici, on a un titre encore moins important

On peut aller de un "#" jusqu'à 6 : "######".

3 Le formatage du texte

*texte en italique*
**texte en gras**
`texte encadré`

Le ` pour encadrer du texte ne doit pas être confondu avec le ' (guillemet simple). Il est obtenu avec la combinaison ALT+è (ALT et la touche 7 du clavier). Ce formatage est plutôt utilisé pour dénoter une bout de code source.

3.1 Texte en couleur

Pour colorer un texte, on doit utiliser la syntaxe HTML.

<span style="color: red">Texte en rouge</span>

Couleurs disponibles https://www.w3schools.com/colors/colors_names.asp https://kramdown.gettalong.org/quickref.html#inline-attributes

4 Les tableaux

Voici un exemple de tableau

| première case  | deuxième case  |
|----------------|----------------|
| troisième case | quatrième case |

Il peut-être fastidieux de gérer un tableau à la main, en rajoutant soi-même les caractères pour qu'il soit équilibré. En utilisant des logiciels comme Atom (Voir section 12).

5 Les listes

  • Pour des listes non-numérotées,
- Premier élément
- Deuxième élément
- etc.
  • Pour des lsites numérotées,
1. Premier élément
2. Deuxième élément
3. etc.

Remarques :

  • Au lieu d'utiliser "-" pour les listes non-numérotées, on peut également utiliser * et +
  • On n'est pas obliger de s'embêter avec les numérotation 1., 2., etc . Par exemple, écrire :

    1. Premier élément
    1. Deuxième élément
    1. etc.
    

    Produira le même résultat que précédemment.

6 Les images

On considère ici que les images sont rangés dans un dossier "images".

Pour ajouter une image :

![Texte à afficher si l'image ne s'affiche pas](./images/nome_de_l_image.png)

Dans Jekyll, on rajoute {{site.url}},

![Texte à afficher si l'image ne s'affiche pas]({{ site.url }}/images/nome_de_l_image.png)

{{ site.url }} est traduit par Jekyll pour comprendre qu'il faut "utiliser les images de ce site", et non aller chercher ailleurs sur internet.

7 Les liens url

Pour ajouter un lien vers une autre page (que ce soit vers un autre site internet ou vers une autre page du même site internet) on utilise des crochets. Par exemple pour mettre un lien vers la page http://google.com, on écrira :

[Cliquez ici pour accéder à Google.com](http://google.com)

On peut mettre une bulle d'information quand la souris survole le lien :

[Cliquez ici pour accéder à Google.com](http://google.com "Bulle d'information")

Si on veut s'affranchir de spécifier le titre du lien qui sera affiché à cliquer :

<http://google.com>

Ça marche aussi pour une adresse email

<boutarst@agayou.com>

7.1 Liens internes

Voir section 11.2.

7.2 Les références

Quand on veut mentionner beaucoup de fois un lien url, il est préférable d'utiliser des références. Imaginons que je veuille placer à plein d'endroits différents dans ma page un lien vers la page http://google.com. Je vais définir une référence que je nomme `google`. Et à l'endroit où je souhaite insérer mon lien url, j'écris :

[Cliquez ici pour accéder à Google.com][google]

On peut également s'affranchir d'écrire un texte, et utiliser le nom de la référence comme texte qui sera affiché :

[google]

En toute fin de page, il faut définir la référence en écrivant écrire :

[google]: http://google.com

8 Les citations

Pour écrire une citation, il faut la faire précéder par ">" :

> De défaites en défaites jusqu'à la victoire finale.

On peut faire tenir une citation sur plusieurs lignes et même inclure des titres dedans :

> # Un jour, un amérindien a dit :
> Chasse deux lièvres à la fois et tu n'en attraperas aucun
> > Voici une autre citation imbriquée

9 Divers

9.1 Trait de séparation

On peut placer un trait de séparation qui prendra toute la largeur en rajoutant, à l'endroit désiré :

Texte avant. Veiller à laisser une ligne vide avant le trait.

---------------
Texte après

Le nombre de tirets importe peu, il en faut au moins 3 pour qu'on comprenne que c'est un trait.

9.2 Utiliser un caractère spécial

On l'a vu, markdown utilise de pas mal de caractères pour formater le document (#, *, -, `, etc). Si malgré tout on veut inclure un tel caractère tel quel dans notre document, il faudra écrire celui-ci précédé d'un \ :

\*
\`
\#
\-

Il est bien sûr également possible d'écrire tel quel le \ :

\\

10 Ajouts de kramdown

10.1 Coloration du texte

Ceci est *rouge*{: style="color: red"}.

10.2 Abbréviations

Ceci ajoutera une bulle d'information quand on passera la souris sur SNCF :

Le réseau ferroviaire est géré par la SNCF.

*[SNCF]: Société Nationale des Chemins de fer Français

11 Spécifique à Jekyll

Cette partie concerne les éléments qui sont utilisés dans le fichier markdown par Jekyll, pour ajouter un formatage supplémentaire au texte.

11.1 Le code source

Pour inclure du code source :

{% highlight ruby %}
def print_hi(name)
puts "Hi, #{name}"
end
print_hi('Tom')
#=> prints 'Hi, Tom' to STDOUT.
{% endhighlight %}

11.2 Liens internes

Si on veut mettre un lien vers une autre page du site :

[Cliquez ici pour accéder à la page]({{ site.baseurl }}{% link chemin/vers/la/page.md %})

Les fichiers sont rangés dans le dossier "assets".

11.2.1 Lien vers un post (article)

{{ site.baseurl }}{% post_url chemin/vers/la/page.md %}

Les fichiers sont rangés dans le dossier "assets".

11.2.2 Lien vers un fichier

Les fichiers pdf, les images, et tout ce qui ne constitue pas du texte, sont placés dans le site dans le dossier "assets". Pour inclure un lien vers un fichier (à télécharger, donc par exemple un pdf) il faut écrire :

[Titre du lien]({{ site.baseurl }}{% link assets/mon_fichier.pdf %})

11.2.3 Rendre une image cliquable

Il est possible de rendre une image cliquable en l'encapsulant dans un lien. Sur l'exemple suivant, en cliquant sur l'image, on sera redirigé vers http://google.com :

[![Texte à afficher si l'image ne s'affiche pas]({{ site.url }}/images/nome_de_l_image.png)](http://google.com)

{{ site.url }} permet en gros de dire "aller chercher les images qui sont sur ce site, et non ailleurs sur internet".

12 Éditeur markdown

D'après mes recherches, le logiciel Atom semble le meilleur choix pour éditer des fichiers markdown.

12.1 Traduire en français

De base, Atom n'est pas en français, mais peut-être traduit en installant le paquet french-menu.

12.2 Ouvrir l'onglet de prévisualisation

Pendant l'édition d'un fichier markdown, on peut ouvrir un onglet qui affichera un rendu du fichier via le raccourci Ctrl-Shift-M

13 Références

Ce document est un condensé des plus importantes notions langage de balisage Markdown. Pour plus de détails, se référer aux liens suivants, qui ont permis la rédaction de cette page :

14 À lire aussi

Auteur: adam - http://ouyaah.legtux.org

Created: 2017-05-01 lun. 20:58

Validate