PHP Markdown Extended est un paquet PHP pour transformer des fichiers texte ou des chaînes de texte au format Markdown en HTML. Cette nouvelle version de Markdown tente de proposer un ensemble complet des règles de syntaxe et est compatible PHP-5.3+.
Qu’est-ce que Markdown?
Créé par John Gruber en 2004, Markdown est, comme il le dit lui-même:
un convertisseur texte-vers-HTML pour rédacteurs web. Markdown autorise à écrire en utilisant du texte brut, facile à lire et facile à écrire, puis de le convertir en un contenu structuré et valide xHTML (ou HTML).
Je dirais pour ma part que Markdown est un panel de règles d’écriture pour construire des contenus texte lisibles et compréhensibles par un humain, comme les fichiers communs .txt, qui peut être transformé en contenu HTML valide et riche, structurellement et du point de vue de la typographie.
Cette syntaxe est devenue l’une des plus utilisée pour des contenus riches, utilisée notamment par GitHub comme l’un des formats proposés pour les fichiers d’information des paquets.
Une courte histoire de Markdown
L’idée première a été développée par John Gruber, codée en Perl.
Une version étendue, connue sous le nom de Markdown Extra, a été implémentée par Michel Fortin, codée en PHP.
Une autre implémentation étendue, connue sous le nom de Multi Markdown, a été écrite par Fletcher T. Penney, codée en Perl.
Alors, pourquoi encore une nouvelle version de Markdown?
- Cette version, connue sous le nom de PHP Markdown Extended, tente de collecter les différentes règles et tags utilisées par les trois versions listées ci-dessus.
- C’est un paquet PHP qui peut être inclus et utilisé dans n’importe quel projet PHP.
- Il est codé en suivant les règles standards du codage PHP 5.3 et est compatible avec Composer.
- Il peut être utilisé en ligne de commande, avec un ensemble d’options.
- Il peut être configuré pour des besoins spécifiques.
- Il est construit de façon à utiliser des entités simples et unitaires qui permettent de l’étendre simplement.
Comment ça marche?
Comme pour tous nos paquets, nous essayons de suivre les règles de codage et de nommage standards:
Sachant cela, les classes du framework sont nommées et organisées dans en architecture autorisant l’utilisation du chargeur automatique standard “SplClassLoader”.
L’ensemble du paquet est inclus dans le namespace MarkdownExtended.
Installation
Vous pouvez utiliser ce paquet dans vos travaux de différentes façons.
D’abord, vous pouvez cloner le dépôt GIT GitHub et l’inclure tel quel dans votre projet:
~$ wget --no-check-certificate http://github.com/e-picas/markdown-extended
Vous pouvez également télécharger une archive depuis Github.
Ensuite, pour utiliser les classes du paquet, vous devez simplement définir son namespace et l’associer au répertoire du paquet, en utilisant par exemple le chargeur standard “SplClassLoader ou tout autre chargeur personnalisé (si besoin, une copie du chargeur standard est incluse dans le paquet):
require_once 'path/to/package/src/SplClassLoader.php';
$classLoader = new SplClassLoader('MarkdownExtended', '/path/to/package/src');
$classLoader->register();
Un autre moyen d’utiliser ce paquet, si vous utilisez Composer, est de l’ajouter dans la liste de vos dépendances dans le fichier composer.json:
"require": {
...
"picas/markdown-extended": "dev-master"
}
Le namespace sera ainsi automatiquement ajouté au chargeur automatique de votre projet par Composer.
Utilisation
Utilisation du script PHP
Le paquet MarkdownExtended est appelé simplement par:
// création d'une instance unique de \MarkdownExtended\MarkdownExtended
$content = \MarkdownExtended\MarkdownExtended::create()
// récupération de l'objet \MarkdownExtended\Parser en lui passant des options (si nécessaire)
->get('Parser', $options)
// lancement de la transformation sur un contenu source
->parse( new \MarkdownExtended\Content($source) )
// récupération du rendu sous forme d'objet
->getContent();
Ceci va charger dans la variable $content la version HTML du contenu initial au format Markdown. Pour récupérer la partie requise de ce contenu, écrivez:
echo $content->getBody();
Pour une utilisation simplifiée, des “alias” sont définis dans le kernel MarkdownExtended:
// pour transformer une chaîne
\MarkdownExtended\MarkdownExtended::transformString($source [, $parser_options]);
// pour transformer le contenu d'un fichier
\MarkdownExtended\MarkdownExtended::transformSource($filename [, $parser_options]);
Ces deux méthodes retournent un objet \MarkdownExtended\Content. Finalement, pour obtenir le contenu HTML:
\MarkdownExtended\MarkdownExtended::transformString($source [, $parser_options]);
echo \MarkdownExtended\MarkdownExtended::getFullContent();
Compatibilité avec les vieilles implémentations
Pour garder ce paquet compatible avec les autres versions de Markdown, une interface est définie avec la fonction classique Markdown($content) ; pour l’utiliser, chargez simplement le fichier src/markdown.php:
require_once 'path/to/src/markdown.php';
// pour transformer une chaîne
echo Markdown($string [, $options]);
// pour transformer un fichier
echo MarkdownFromSource($file_name [, $options]);
Utilisation en ligne de commande
Une interface en ligne de commande est disponible dans le paquet, en exécutant:
~$ bin/markdown-extended --help
Cette interface permet de transformer un ou plusieurs fichiers, d’extraire des informations depuis ces sources, d’écrire le résultat dans un ou plusieurs fichiers et d’autres chose encore.
Pour générer la page de manuel de l’interface depuis le fichier docs/MANPAGE.md en utilisant l’interface elle-même, exécutez:
~$ bin/markdown-extended -f man -o bin/markdown-extended.man docs/MANPAGE.md
~$ man ./bin/markdown-extended.man
Utilisation avec Apache
Un exemple d’appel direct par Apache du gestionnaire Markdown est défini dans le répertoire demo/cgi-scripts/. Cela permet de transformer automatiquement tout fichier Markdown en contenu HTML tout en conservant la navigation classique d’Apache. Pour aller plus loin sur cette fonctionnalité, voyez la page de documentation dédiée How-To.
Open-Source & Communauté
Ce paquet est un logiciel libre, proposé sour licence BSD ; vous pouvez l’utiliser librement et gratuitement, pour vous-même ou à des fins commerciales, modifier ses sources selon vos besoins, redistribuer librement votre travail et le proposer à la communauté, tant que vous laissez visible une information de protection sur ses auteurs initiaux.
Les sources étant hébergées sur un dépôt GIT sur le site GitHub, vous pouvez les modifier, pour améliorer le paquet ou corriger une erreur, en créant votre “fork” du dépôt, le modifiant puis en nous demandant de “merger” vos modifications sur la branche originale.
Veuillez noter que la branche “master” est toujours la dernière version stable du code. Les développements sont faits sur la branche “wip” et vous pouvez créer la vôtre pour vos propres développements. Une aide et une feuille de route pour développeurs est proposée (en anglais), dans les documentations. La dernière version de la documentation du paquet est disponible en ligne à l’adresse http://docs.ateliers-pierrot.fr/markdown-extended/.
Veuillez noter que le paquet est intégré au projet Travis CI.
Licences
Ce logiciel, comme la version originale de Markdown, est protégé par les termes de la licence BSD-3-Clause open source license.
Vous pouvez utiliser, transformer et distribuer ce logiciel et ses dépendances comme bon vous semble, tant que vous mentionnez les droits d’auteur ci-dessous:
Mardown
Copyright © 2004-2006, John Gruber
http://daringfireball.net/
All rights reserved.
MultiMarkdown
Copyright © 2005-2009 Fletcher T. Penney
http://fletcherpenney.net/
All rights reserved.
PHP Markdown & Extra
Copyright © 2004-2012 Michel Fortin
http://michelf.com/projects/php-markdown/
All rights reserved.
Markdown Extended
Copyright © 2008-2013 Pierre Cassat & contributors
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are
permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of
conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list
of conditions and the following disclaimer in the documentation and/or other materials
provided with the distribution.
- Neither the name “Markdown” nor the names of its contributors may be used to endorse
or promote products derived from this software without specific prior written permission.
This software is provided by the copyright holders and contributors “as is” and any
express or implied warranties, including, but not limited to, the implied warranties
of merchantability and fitness for a particular purpose are disclaimed. In no event
shall the copyright owner or contributors be liable for any direct, indirect,
incidental, special, exemplary, or consequential damages (including, but not limited
to, procurement of substitute goods or services; loss of use, data, or profits; or
business interruption) however caused and on any theory of liability, whether in
contract, strict liability, or tort (including negligence or otherwise) arising in
any way out of the use of this software, even if advised of the possibility of such
damage.