07 Markdown

Markdown

Markdown est un langage de balisage léger créé en 2004 par John Gruber avec Aaron Swartz. Son but est d'offrir une syntaxe facile à lire et à écrire. Un document balisé par Markdown peut être lu en l'état sans donner l’impression d'avoir été balisé ou formaté par des instructions particulières.

Il s'agit de la syntaxe utilisée pour la rédaction de l'ensemble des TPs de ce site.

Quelques exemples

Pour mettre du texte en emphase (balise HTML <em>), ce qui produit une mise en italique dans un navigateur courant :

*quelques mots* ou  _quelques mots_

Pour mettre du texte en grande emphase (balise HTML <strong>), ce qui produit une mise en gras dans un navigateur courant :

**plus important**

Pour souligner :

__également important__

Pour créer une liste non ordonnée (balise HTML <ul>) :

* Pommes
* Poires
    * Sous élément avec au moins quatre espaces devant.

Et une liste ordonnée (balise HTML <ol>) :

1. mon premier
2. mon deuxième

Les titres sont créés avec un certain nombre de # avant le titre, qui correspondent au niveau de titre souhaité (le HTML propose 6 niveaux de titres de <h1> à <h6>)

# un titre de premier niveau
#### un titre de quatrième niveau

Pour créer des liens (balise HTML <a>) :

[texte du lien](url_du_lien)

Pour afficher une image (balise HTML <img>) :

![Texte alternatif](url_image)

Un exemple

# Header

Paragraphs are separated by a blank line.

2nd paragraph. *Italic*, **bold**, and `monospace`. Itemized lists
look like:

  * this one
  * that one
  * the other one

Note that --- not considering the asterisk --- the actual text
content starts at 4-columns in.

> Block quotes are
> written like so.
>
> They can span multiple paragraphs,
> if you like.

Mise en oeuvre

Plusieurs librairies existent et ce dans différents langages de programmation :

• en Perl,
• en PHP,
• en Ruby,
• en Python ❤️,
• en Java,
• en C#,
• en R et même en JavaScript.

En PHP

Pour générer du HTML à partir de markdown on utilise en PHP la librairie michelf/php-markdown (composer require ?)

Dans votre fichier functions.php, ajouter la fonction suivante:

<?php
use Michelf\Markdown;

function renderHTMLFromMarkdown($string_markdown_formatted)
{
    return Markdown::defaultTransform($string_markdown_formatted);
}

Et si nous ajoutions une route (markdown_test) pour utiliser notre fonction ?

<?php
Flight::route('/markdown_test', function(){
    echo renderHTMLFromMarkdown("##HELLO WORLD!");
});

• En vous rendant sur l'url /markdown_test que constatez vous ?

Allons un peu plus loin

Il est plus intéressant de stocker le contenu de nos pages statiques (présentation de l'entreprise, mentions légales, à propos, ..) dans différents fichiers puis de lire leurs contenu à la demande.

Préparation de l'architecture

• Créer dans à la racine de votre projets un répertoire pages\
• Créer dans le répertoire pages\ un fichier test.md avec le contenu suivant:

## Test

Récupérer le contenu d'un fichier

Pour récupérer le contenu d'un fichier, PHP nous fournit la fonction file_get_contents.

Ainsi nous pouvons créer dans notre fichier tests/UnitariesTest.php la fonction de test suivante:

<?php
public function test_readFileContent(){
    $this->assertEquals("## Test", readFileContent("pages/test.md"));
}

• On relance notre suite de tests, test_readFileContent échoue .. parfait !
• Ajoutons la fonction readFileContent

<?php
function readFileContent($filepath){
    return file_get_contents($filepath);
}

• Remplacer dans notre controller pour /markdown_test, la string ##HELLO WORLD par le contenu du fichier pages/test.md

À vous de jouer !

1. Créer un template Twig pour afficher le contenu de votre page dans un template HTML,
2. Le code HTML produit s'affiche correctement ? L'utilisation du filtre raw pourra vous être utile,
3. Créer une fonction readPagesContent qui prend en paramètre uniquement le nom de votre fichier .md (sans l'extension .md) et qui vous retourne le contenu de la pages (TDD?),
4. Convertir le markdown en HTML n'est pas un job pour notre controller, il s'agit d'un boulot pour notre vue ! Créer un filtre Twig pour convertir du Markdown en HTML (cf. TP sur Twig).

Rappel

La fonction sprintf permet de faire du formatage de chaîne de caractéres.

<?php
$name = "Ben";
$hello_string = sprintf("hello %s", $name); // Hello Ben