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

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 &lt;) de passer directement à la sortie tel que le spécifie la syntaxe Markdown. À la place, la sortie HTML sera &amp;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 tolower($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 ($header) {
    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 personalisé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 personalisé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.

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_html = "&#8617;&#xFE0E;"

Contenu HTML du lien de retour d’une note de bas de page. Le suffixe &#xFE0E; 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.

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 occurance 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.

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.


  • © 2003–2017 Michel Fortin.