PHP Markdown : Configuration

PHP Markdown Lib inclus deux parseurs: Markdown et MarkdownExtra. Voici la liste des variables de configuration accessible pour chacun d’eux.

Configurer le parseur
Configuration pour Markdown
Configuration pour Markdown Extra
Différences avec la version classique

Configurer le parseur

En général, la configuration par défaut devrait faire l’affiare. Pour ces situations vous n’avez qu’à appeler la fonction defaultTransform sur la classe du parseur :

use Michelf\Markdown;
$html = Markdown::defaultTransform($text);

Pour les cas où certaines choses doivent fonctionner différament, créez une instance du parseur et réglez quelque variables :

use Michelf\Markdown;
$parser = new Markdown;
$parser->empty_element_suffix = ">";
$html = $parser->transform($text);

Le options de configuration du parseur MarkdownExtra fonctionne de la même façon.

Configuration pour Markdown

empty_element_suffix = " />"

Chaîne utilisé pour fermer les balises HTML sans contenu, tel que <br> et <hr>. La valeur par défaut crée des balises auto-fermées de style XML, qui sont aussi valides en HTML 5.

tab_width = 4

Largeur d’un caractère de tablulation à l’entrée. Changer cette valeur affectera le nombre d’espace représenté par un caractère de tabulation.

Note : Gardez à l’esprit que lorsque la syntaxe Markdown spécifie “quatre espaces ou une tabulation”, ça signifie en réalité “quatre espaces après la conversion des tabulations en espaces”. Donc régler tab_width à 8 fera en sorte que le parseur traitera une tabulation comme deux niveaux d’indentation.

hard_wrap = false

Régler ceci à true changera les sauts de lignes en <br /> quand le contexte le permet. Sinon, suivant la sytaxe Markdown standard ces sauts de ligne sont ignorés à moins d’être précédés par deux espaces.

no_markup = false

Régler cette variable à true empêchera les balises HTML à l’entrée de se rendre à la sortie.

Important : Ceci n’est pas une protection contre les scripts javascript pouvant être injectés dans un document. Voyez pourquoi dans Markdown et XSS.

no_entities = false

Régler cette variable à vrai empêchera les entitées HTML (tel que <) de passer directement à la sortie tel que le spécifie la syntaxe Markdown. À la place, la sortie HTML sera &lt; et correspondra exactement à ce qui a été écrit une fois visible dans le navigateur.

predef_urls = array()

Vous pouvez prédéfinir des références pour des liens en réglant predef_urls à une liste d’URL utilisant la référence comme clé. Par exemple :

$parser->predef_urls = array('ref' => 'https://michelf.ca/');

fera en sorte que cet entrée Markdown créra un lien :

Ceci est [mon site][ref].

predef_titles = array()

Utilisez predef_titles pour donner un titre aux références pour les liens passés dans predef_urls. Comme pour predef_urls, la clé est le nom de la référence.

url_filter_func = null

Cette variable permet de transfomer les URLs des liens et des images dans le document à partir d’une une fonction:

$parser->url_filter_func = function ($url) {
    return strtolower($url);
};

Ceci peut être utiliser pour sécuriser des URLs, compléter les URLs locales, etc.

header_id_func = null

Les titres peuvent avoir des attributs id générés automatiquement en réglant cette variable de configuration à une fonction:

$parser->header_id_func = function ($text) {
    return preg_replace('/[^a-z0-9]/', '-', strtolower($text));
};

code_block_content_func = null

Le contenu des blocs de code peut être transformé en HTML avec une fonction personnalisée. Une version simpliste de cette fonction ne fera que changer les caractères spéciaux en entités HTML:

$parser->code_block_content_func = function ($code, $langage) {
    return htmlspecialchars($code);
};

Une version plus poucée pourrait utiliser le paramètre $langage pour faire de la coloration syntaxique. Le résultat retourné par la fonction est automatiquement envelopé dans un <pre><code>.

code_span_content_func = null

Le contenu des étendues de code peut être transformé en HTML avec une fonction personnalisée. Une version simpliste de cette fonction ne fera que changer les caractères spéciaux en entités HTML:

$parser->code_span_content_func = function ($code) {
    return htmlspecialchars($code);
};

Une version plus poucée pourrait deviner le language pour et faire de la coloration syntaxique. Le résultat retourné par la fonction est automatiquement envelopé dans un <code>.

enhanced_ordered_list = false

Régler cette variable à true permettra les listes ordonnées commençant par un numéro différent de 1.

(Note : ceci est réglé à true par défaut pour Markdown Extra.)

Configuration Markdown Extra

En plus de toutes les variables de configuration dans le parseur Markdown, le parseur MarkdownExtra possède les réglages suivant.

fn_id_prefix = ""

Un préfixe pour l’attribut id généré par les notes de bas de page. Ceci est pratique si vous avez plusieurs document Markdown affichés à l’intérieur d’un même document HTML pour éviter d’avoid plusieurs id identiques.

fn_link_title = ""

fn_backlink_title = ""

Un titre optionnel pour les liens des notes de bas de page et des liens de retour. Les navigateurs affichent généralement ceci à l’intérieur d’une bulle d’aide quand le pointeur se s’arrête au dessus du lien.

Pour les liens de retour, le titre est aussi utilisé comme identifiant d’accessibilité avec l’attribut aria-label.

Les occurances de “^^” dans la chaîne seront remplacées par le numéro de la note. Les occurances de “%%” seront remplacées par le numéro de la référence (une note peut avoir plusieurs références).

fn_link_class = "footnote-ref"

fn_backlink_class = "footnote-backref"

L’attribut class ajouté aux liens des notes de bas de page et aux liens de retour.

fn_backlink_label = ""

Ajoute une étiquette d’accessibilité pour les liens de retours (l'attribut
`aria-label`), à utiliser si vous désirez un texte différent de celui dans
l'attribut `titre`.

Les occurances de "`^^`" dans la chaîne seront remplacées par le numéro de
la note. Les occurances de "`%%`" seront remplacées par le numéro
de la référence (une note peut avoir plusieurs références).

fn_backlink_html = "↩︎"

Contenu HTML du lien de retour d’une note de bas de page. Le suffixe ︎ dans la valeur par défaut permet d’éviter que la flèche courbée apparaîsse sous la forme d’un Emoji sur les appareils mobiles, mais ça pourrait faire apparaître un caractère non-reconnu sur les anciens navigateurs.

omit_footnotes = false

Si réglé à true, les notes de bas de pages ne feront pas partie de la sortie HTML et la variable footnotes_assembled contiendra le code HTML pour la liste des notes. Ceci permet de placer les notes ailleurs sur la page.

Note: en plaçant le contenu de footnotes_assembled sur la page, pensez à ajouter l’attribut role="doc-endnotes" à l’élément <div> ou <section> dans laquelle vous placez la liste des notes pour permettre aux outils d’accessibilité de les repérer.

code_class_prefix = ""

Un préfixe optionnel pour les noms de classe associés aux blocs de code balisés. Cette chaîne est ajouté au début du nom de la classe si vous écrivez votre bloc de code balisé de cette façon :

~~~~ .html
<br>
~~~~

Notez cependant que ceci n’a aucun effet si vous ajoutez le nom de classe en utilisant la syntaxe d’attribut supplémentaire plus générique avec des accolades :

~~~~ {.html .flashy}
<br>
~~~~

code_attr_on_pre = false

Si réglé à false (la valeur par défaut), les attributs pour un bloc de code iront sur la balise <code>; réglé à true les attributs iront sur la balise <pre> à la place.

table_align_class_tmpl = ""

Valeur pour l’attribut class déterminant l’alignement du contenu des cellules dans un tableau tableaux. Par défaut, ou si laissé vide, l’attribut align est utilisé au lieu de class pour spécifier l’alignement.

Si non-vide, l’attribut align n’apparaîtrera pas. À sa place, l’attribut class sera déterminé en remplaçant toute occurrences de %% dans la chaîne par left, center ou right. Par exemple, si la variable de configuration est réglée à "go-%%" et que la cellule est aligné à droite, le résultat sera class="go-right".

predef_abbr = array()

Vous pouvez prédéfinir des abréviations en réglant predef_abbr à une liste d’abbréviations où la clé est le texte de l’abbréviation et la valeur est le nom complet.

hashtag_protection = false

Réglez à true pour empêcher la formation d’un titre de style ATX qui ressemble à un #hashtag. Une espace après le # sera nécessaire afin de former un titre.

Différences avec la version classique

Les options de configuration de la version classique sont relativement similaires à celle de PHP Markdown Lib décrites ci-haut. Voici cependant quelque différences.

Pour la version classique les classes sont nommées Markdown_Parser et MarkdownExtra_Parser, sans espace de nom.

La fonction defaultTransform n’existe pas. À la place, une fonction globale Markdown est disponible et utilise Markdown_Parser ou MarkdownExtra_Parser selon le fichier téléchargé. On peut changer la classe appelé par la fonction Markdown en définissant la constante MARKDOWN_PARSER_CLASS avant d’inclure le fichier.

Les options par défaut sont définies dans des constantes que l’on peut définir avant d’inclure le fichier.

Dans la version classique un attribut rel="footnote" est ajouté sur les liens menant aux notes de bas de page et rev="footnote" sur les liens de retour. Dans la configuration par défaut il n’y a aucun attribut class. La version Lib remplace rel et rev par l’attribut class décrit plus haut dans ce document.