Kramdown style guide

table des matières

Documentation kramdown
Balises markdown courantes
Utilisation avancée
(Info/warning/danger)
Outils utilisés

Documentation kramdown

Cette page résume l’utilisation des balises markdown/kramdown et les règles d’utilisation (style guide) dans la documentation de ce site. La documentation est adapté de Gitlab.

Quelques liens
Gitlab : Le markdown expliqué
Gitlab : style guide

Balises markdown courantes

Retour à la ligne dans un paragraphe

Par défaut, le texte dans un document md, même avec un retour à la ligne fait parti du même paragraphe.
Pour forcer le retour à la ligne, terminer celle-ci par espace espace entrée

Titre dans le document

Ne pas utiliser le titre h1 dans le document. Cela génère des liens inapropriés

## header 2

### header 3

Ligne séparatrice

Pour avoir une ligne horizontale dans le document, insérer au moins 4 tirets (-—) à la suite.

Gras et italique

Pour que le texte soit en gras ou italique, utiliser : **gras** et _italique_

gras et italique

CSS dans le code

On peut faire référence à des classes css dans le code
On peut aussi spécifier l’id d’un élément en utilisant le #

.blue {
  color: blue;
}

# Shopping list
{: .blue #blue-h}

Shopping list

Note
Pour faire des notes dans le document, utiliser la class css .note définie dans stylesheet.css

.note {
  font-size: 16px;
  font-style: italic;
  color: #666;
}

**Note:** Ceci est une note
{: .note}

Note: Ceci est une note

Liste (non ordonnée et ordonnée)

Pour faire une liste non ordonnée

* cheville
* maléole
* genoux

cheville
maléole
genoux

Et ainsi de suite

Pour faire une liste ordonnée

Bread
Butter
Refined uranium

Bread
Butter
Refined uranium

Blockquote

Les blockquotes permettent de faire des citations

> Ceci est un block quote
>     sur plusieurs lignes.
encore la même ligne
>
> Ceci est le second paragraphe.

Ceci est un block quote sur plusieurs lignes. encore la même ligne

Ceci est le second paragraphe.

Liens et images

Liens Pour faire un lien, c’est [texte](lien)
Si on ajoute :target=”_blank”, cela ouvre le lien dans un nouvel onglet

[Text to display](link)
[google](http://google.com)
[Text to display](link){:target="_blank"}

google

google dans un nouvel onglet

Images Les images sont des sortes de liens, précédé de !

Note: {: .shadow} permet de d’ombrer l’image, {: height=”250px”} de choisir la taille de l’image

![Semantic description of image](/images/path/to/folder/image.png "Image Title")
Exemple
![Tux](/pub/images/pirat_tux.jpg "Tux le pirate"){: .shadow}{: height="250px"}

Tux

Intégrer une vidéo YouTube

Au début de votre fichier .md, placer l’ID de la vidéo YouTube

---
youtubeId: putYourIDHere
---

Placer cet extrait de code dans le fichier .md où vous voulez intégrer la vidéo.

{% include youtubePlayer.html id=page.youtubeId %}

Identificateur et liens

Pour faire un lien dans le document, on peut utiliser les identificateurs dans le document et renvoyer vers le lien. Il faut entourer l’identificateur de crochets [identificateur] et préciser ensuite le lien correspondant.

[identificateur]: https://monsuperlien.com/

Utilisation avancée

Cacher et découvrir une note (collapse)

On utilise la balise html detail dans le markdown

Collapse

<details>
  <summary markdown="span">Ceci est le résumé, cliquez moi pour voir le texte détaillé</summary>
  Ceci est le texte détaillé

  * Vegetables
  * Fruits
  * Fish

  Pour que cela fonctionne bien, il faut ajouter \{::options parse_block_html="true" /} avant
</details>

Ceci est le résumé, cliquez moi pour voir le texte détaillé

Ceci est le texte détaillé

Vegetables
Fruits
Fish

Pour que cela fonctionne (bien), il faut ajouter {::options parse_block_html=”true” /} avant

Collapse2

<details>
  <summary markdown="span">I could use some help...</summary>

  <!-- ~~~c#
  public class Order
  {
      public int OrderId { get; set; }
      public int CustomerId { get; set; }

      public List<int> Products { get; set; }
  }
  ~~~ -->

</details> 

I could use some help…

  public class Order
  {
      public int OrderId { get; set; }
      public int CustomerId { get; set; }

      public List<int> Products { get; set; }
  }

Block de code

The killer fonction pour cette doc. Va permettre de coloriser le code en fonction du langage

Block de code

Il faut entourer le block de code de ~~~ avant et après le bloc On peut préciser le langage de programmation pour la coloration syntaxique (ruby, md, cpp, shell, …)

\~~~ ruby
def hello
  puts "Hello world!"
end
\~~~

def hello
  puts "Hello world!"
end

Block de code dans une liste ordonnée
On peut mixer les balises, comme pour ici insérer des blocks de code dans ma liste ordonnée.

Indenter le text de chaque item avec 3 espaces. Laisser une ligne blanche entre le bloc de code et les items de la liste. Indenter le code avec 5 espaces.

1.   Item 1
1.   Item 2

     ~~~ ruby
     def hello
        puts "Hello world!"
     end
     ~~~

1.   Item 3

Item 1
Item 2
```
def hello
   puts "Hello world!"
end
```
Item 3

Ajouter des icônes dans le texte

Font awezone

Font awezone est un service pour ajouter des icones sur des pages web Pour l’utiliser, après inscription, il faut ajouter le script dans le head du layout principal

  <p>La première ligne (commentée) est pour la version 4, la seconde pour la version 5</p>
  <!-- <script src="https://use.fontawesome.com/2682010429.js"></script> -->
  <script src="https://kit.fontawesome.com/245306b796.js" crossorigin="anonymous"></script>

Ensuite, il suffit d’aller chercher l’icône voulu sur le site et de copier le code. Ne pas oublier d’ajouter un identifiant correct en dessous. Sinon, on utilise l’identifiant par défaut de FA.

<i class="fas fa-puzzle-piece" aria-hidden="true"></i> Puzzle Icon
{: #puzzle}

<i class="fa fa-thermometer-empty" aria-hidden="true"></i> Thermomètre
{: #thermometre}

Puzzle Icon

Thermomètre

Texte en surbrillance lors d’un survol

On a défini la classe .purple dans le css pour que certains texte puissent changer de couleur lors du suvol

.purple {
  color:inherit;
}

.purple:hover {
  color:rgb(107,79,187);
}

Hey ! Survolez moi avec la souris et devinez !?! :)
{: .purple}

Hey ! Survolez moi avec la souris et devinez !?! :)

Intégrer des snippets (extrait de code)

On peut intégrer très facilement des extraits de code de gitlab. Il suffit de récupérer le code de l’intégration sur gitlab et de l’insérer dans un markdown

<!-- leave a blank line here --> 
<script src="https://gitlab.ciel-kastler.fr/-/snippets/8.js"></script>>
<!-- leave a blank line here --> 

(Info/warning/danger)

Les styles de card utilisés sont extrait du css de Bootstrap. Le css nécessaire à été ajouté à notre fichier custom.css

{::options parse_block_html="true" /}
...
//code bootstrap
...
{::options parse_block_html="false" /}

Les cards

Une carte info

<div class="card text-white bg-primary">
**Note**
{: .card-header }
<div class="card-body text-black bg-light ">

NOTE DESCRIPTION

</div>
</div>

Note

NOTE DESCRIPTION

Une autre carte pour le danger

<div class="card text-white bg-danger mb-2">
**Don'ts**
{: .card-header}
<div class="card-body text-black bg-light">
NOTE DESCRIPTION
</div>
</div>

Don’ts

NOTE DESCRIPTION

les blocks d’alertes

Les alertes vont nous servir à attirer l’attention du lecteur sur un point important

Alerte info

Ceci est une information
{: .alert .alert-info}

Ceci est une information

Alerte warning

Ceci est un warning
{: .alert .alert-warning}

Ceci est un warning

Alerte danger

Ceci est dangereux !
{: .alert .bg-danger .text-white}

Ceci est dangereux !

Intégrer du code Jekyll sans qu’il soit interprété

On utilise raw et endraw autour du code à intégrer avec des %

Outils utilisés

Création de diagrammes Diagrams.net
Screencast de terminal Asciinema
Création de badges Badge design
Compilateur en ligne Gdb Online