PHP Markdown

Téléchargement

PHP Markdown 1.0.1l (24 Ko): Dernière version de PHP Markdown, en date du 11 mai 2008.
PHP Markdown Extra 1.2 (33 Ko): Une version spéciale de PHP Markdown avec des options supplémentaires. Voyez la description de PHP Markdown Extra. Le 11 mai 2008.

PHP Markdown et PHP Markdown Extra sont aussi disponible en packages PEAR.

Si vous aimez ce logiciel et voulez m’encourager à continuer son développement, vous êtes invités à contribuer par un don.

Introduction

PHP Markdown est une conversion en PHP du programme Markdown de John Gruber.

Markdown, c’est deux choses : c’est une syntaxe qui vous permet d’écrire de façon naturelle en format texte ; c’est aussi un logiciel qui permet de convertir du texte écrit selon la syntaxe Markdown en code HTML pour la publication sur un site web.

La syntaxe Markdown vous permet d’écrire naturellement du texte et de lui donner un certain format sans avoir à utiliser de balise HTML. Plus important encore : en format Markdown, votre texte reste agréable à lire pour un être humain, et c’est suffisamment vrai pour qu’un document écrit avec Markdown puisse être publié textuellement, sans modification. Si vous utilisez le courrier électronique en mode texte, vous connaissez déjà certaines parties de la syntaxe.

Visitez la page Concepts pour une courte introduction remplie d’exemples qui vous apprendra à écrire avec Markdown. Si vous connaissez bien le HTML, vous pouvez aussi consulter la syntaxe complète qui explique en détail l’opération de conversion du texte vers le HTML.

PHP Markdown peut fonctionner en tant que plug-in pour WordPress et bBlog, en tant que filtre pour le système de patron Smarty, ou en remplacement du filtre Textile dans n’importe quel logiciel qui supporte Textile.

Installation et configuration requise

PHP Markdown nécessite la version 4.0.5 ou plus récente de PHP.

WordPress

PHP Markdown fonctionne avec WordPress, version 1.2 ou plus récente. PHP Markdown est déjà distribué avec WordPress. Vous trouverez cependant ici la dernière version qui sera peut-être plus récente que celle fournie avec la dernière distribution de WordPress.

Pour usiliser PHP Markdown avec WordPress, placez le fichier « markdown.php » dans le dossier « plugins » de WordPress. Ce dossier devrait se trouver à l’intérieur du dossier « wp-content » à la base de votre site :
```
(base du site)/wp-content/plugins/
```
Activez le plugin à l’aide de l’interface d’administration de WordPress. Dans la section « Plugins », vous trouverez une liste dans laquelle figure désormais Markdown. Cliquez sur le bouton « Activate » de la ligne du tableau où figure Markdown. Vos entrées seront maintenant formatées par PHP Markdown.
Pour ajouter du contenu avec Markdown, vous devrez d’abord désactiver l’éditeur « visuel » dans la section Utilisateur de WordPress.

Vous pouvez configurer PHP Markdown pour qu’il ne s’applique pas aux commentaires de votre blogue WordPress. Voir la section « Configuration » ci-bas.

bBlog

PHP Markdown fonctionne aussi avec bBlog.

Pour utiliser PHP Markdown avec bBlog, renommez le fichier « markdown.php » en « modifier.markdown.php » et placez-le dans le dossier « bBlog_plugins ». Ce dossier se trouve dans le dossier « bblog » de votre site, comme ceci :

(base du site)/bblog/bBlog_plugins/modifier.markdown.php

Sélectionnez « Markdown » comme « Modificateur d’entrée » (Entry Modifier en anglais) quand vous ajouterez une nouvelle entrée. Ce réglage s’appliquera uniquement à l’entrée que vous éditez.

Remplacement de Textile dans TextPattern

TextPattern utilise Textile pour formater le texte. Vous pouvez remplacer Textile par Markdown dans TextPattern sans avoir à changer de code en utilisant le mode de compatibilité avec Textile. Ceci peut fonctionner avec d’autres logiciels utilisant Textile aussi.

Renommez le fichier « markdown.php » en « classTextile.php ». Ceci fera en sorte que PHP Markdown se comporte comme le convertisseur de Textile.
Remplacer le fichier « classTextile.php » que TextPattern installe dans le répertoire web. On peut le trouver dans le dossier « lib » :
```
(base du site)/textpattern/lib/classTextile.php
```

Contrairement à Textile, Markdown ne rend pas les guillemets courbes et ne convertit pas les trait-d’union multiples (-- et ---) en tirets courts et long. Si vous utilisez PHP Markdown en mode compatible Textile, vous pouvez palier à ce problème en installant le fichier « smartypants.php » de PHP SmartyPants à côté du fichier « classTextile.php ». La fonction de compatibilité Textile utilisera SmartyPants automatiquement sans nécessiter de modification supplémentaire.

Dans vos programmes

Vous pouvez utiliser PHP Markdown facilement dans vos programmes PHP. Vous n’avez qu’à inclure le fichier et ensuite appeler la fonction Markdown avec le texte à convertir :

include_once "markdown.php";
$mon_html = Markdown($mon_texte);

Si vous voulez utiliser PHP Markdown avec une autre fonction filtre conçue pour du HTML, vous devrez filtrer le texte après l’appel de la fonction Markdown. Voici un exemple avec PHP SmartyPants :

$mon_html = SmartyPants(Markdown($mon_texte));

Avec Smarty

Si votre programme utilise Smarty, PHP Markdown peut être utilisé comme modificateur dans vos patrons de pages. Renommez le fichier « markdown.php » par « modifier.markdown.php » et placez-le dans le dossier de plugins de Smarty.

Si vous utilisez MovableType, version 3.1 ou plus récente, le dossier de plugins de Smarty se trouve à (Racine CGI de MT)/php/extlib/smarty/plugins. Placer « modifier.markdown.php » dans ce dossier vous permettra de faire fonctionner Markdown sur les pages dynamiques.

Mettre à jour Markdown dans d’autres programmes

Plusieurs applications web viennent maintenant avec PHP Markdown, ou ont des modules permettant de faire la conversion en HTML. Vous pouvez mettre à jour PHP Markdown — ou le remplacer par PHP Markdown Extra — dans plusieurs de ces programmes en échangeant l’ancien fichier “markdown.php” par le nouveau.

Voici une liste non-exhaustive de certains programmes et de où ils cachent le fichier “markdown.php”.

Programme	Chemin vers Markdown
Pivot	`(base du site)/pivot/includes/markdown/`

Si vous n’êtes pas certain de si vous pouvez faire ça avec votre application, demandez au développeur, ou attendez qu’il mettre à jour son application ou son module avec la nouvelle version de PHP Markdown.

Configuration

Par défaut, PHP Markdown produit une sortie XHTML pour pour les tags des éléments vides. Par exemple :

<br />

Markdown peut être configuré pour produire des tags de sytle HTML :

<br>

Pour cela, vous devez éditer la définition MARKDOWN_EMPTY_ELEMENT_SUFFIX sous le titre « Global default settings » au début du fichier.

Réglages spécifiques à WordPress

Par défaut, le plugin Markdown s’applique autant aux entrées qu’aux commentaires de votre blogue WordPress. Pour désactiver l’un ou l’autre, éditez la définition MARKDOWN_WP_POSTS ou MARKDOWN_WP_COMMENTS sous le titre « WordPress settings » au début du fichier.

Bogues

Pour signaler un problème, contactez moi par courriel à cette adresse : michel.fortin@michelf.com

Merci d’inclure : (1) un exemple du texte d’entrée ; (2) la sortie à laquelle vous vous attendiez ; (3) la sortie que PHP Markdown a produite.

Historique

L’historique détaillé des changements est disponible en anglais.

1.0.1l & Extra 1.2 (11 mai 2008)

1.0.1k & Extra 1.1.7 (26 septembre 2007)

1.0.1j & Extra 1.1.6 (4 septembre 2007)

1.0.1i & Extra 1.1.5 (31 août 2007)

1.0.1h & Extra 1.1.4 (3 août 2007)

1.0.1g & Extra 1.1.3 (3 juillet 2007)

1.0.1f & Extra 1.1.2 (7 février 2007)

1.0.1e & Extra 1.1.1 (28 décembre 2006)

1.0.1d (1 décembre 2006)

1.0.1c (9 décembre 2005)

1.0.1b (6 juin 2005)

1.0.1a (15 avril 2005)

1.0.1 (17 décembre 2004)

1.0 (21 août 2004)