Carnet Wiki

Intégrer le contenu d’un fichier markdown dans un article

m-à-j du 24/11/2014 : les modifications évoquées dans cet article sont intégrées dans le plugin Markdown à partir de la version 0.14.1, et ne sont donc valables que pour les versions antérieures.
Le plugin Markdown est téléchargeable à cette adresse : https://github.com/Cerdic/markdown/releases

En 2 mots : dans un texte, une balise <embxx> faisant référence à un fichier markdown (externe ou non) va intégrer le texte mis en forme. Magique !


Sur une idée de Suske qui a partagé une astuce pour intégrer le contenu d’un fichier texte externe dans un article, voyons voir comment faire pour bénéficier en plus de la mise en forme quand il s’agit d’un fichier Markdown.
Markdown est un langage de balisage léger offrant une syntaxe facile à lire et à écrire. Les fichiers Markdown sont des fichiers textes portant l’extension .md.

Pour les articles de documentation les plugins, ça permettrait d’incorporer de façon transparente des README.md, des TODO.md ou des CHANGELOG.md externes et automatiquement tenus à jour.

Attention, il ne s’agit pas d’un tutoriel, mais de mes notes pour faire marcher le schmilblik : n’hésitez pas à commenter et à corriger si nécessaire.

1- Plugin Markdown

Il faut avant tout installer le plugin markdown pour SPIP. Il est développé sur github et disponible également sur la zone.
Pour rappel, dans le texte d’un article on met soit le texte Markdown entre balises <md>...</md>, soit le texte SPIP entre balises <spip>...</spip> selon la configuration.

2- Modèle <emb> pour les fichiers markdown

Maintenant, il nous faut une variante du modèle emb.html du plugin Médias qui sera utilisée automatiquement avec les fichiers Markdown. Le modèle de base regarde s’il existe une variante pour chaque extension, de la forme emb_{extension}.html, on va donc créer un nouveau squelette nommé emb_md.html.

Dans notre squelette, la balise [(#FICHIER|contenu_document)] (ou [(#ID_DOCUMENT|contenu_document)]) récupère le contenu du fichier texte.
On fait en sorte qu’il soit traité par le parseur Markdown en le plaçant entre des balise <md>...</md>, au moyen du filtre |wrap{<md>}.
Après ça, un coup de |propre et le tour est joué.
Ce qui donne au final :

<BOUCLE_tous (DOCUMENTS types_documents) {id_document=#ID} {tout}
>[(#FICHIER|contenu_document{#ENV{charset,auto}}|wrap{'<md>'}|propre)]</BOUCLE_tous>

A noter : on ne s’est pas soucié de placer le tout dans une <div class='spip_documents'>, ni d’afficher le titre du document à la suite. Si besoin, jeter un coup d’oeil au modèle text.html et faire en fonction.

3- Plugin Médias

Il reste un dernier problème à régler : pour l’instant le plugin Médias ne reconnaît pas l’extension .md, par défaut il identifiera ces fichiers comme étant des .m3u (liste de lecture MP3), ce qui va tout fausser.

Il faut ajouter une ligne pour l’extension md dans la table spip_documents_types en se référant aux infos de Shared Mime Info.

spip_documents_types
extension titre descriptif mime_type inclus upload media_defaut
md Markdown document text/x-markdown embed oui file

Pour bien faire, il faudrait également ajouter l’extension dans le fichier base/typedoc.php, mais concrètement, ce fichier n’est utilisé qu’à l’installation pour peupler la table ci-dessus, donc pas utile pour ces tests.


Tester

Voilà, à partir de là ça devrait marcher.
On peut tester en ajoutant par exemple quelques fichiers de tests du plugin markdown comme documents joints externes :

Insérés dans le texte d’un article avec des <embXX>, hop, ils devraient être mis en forme automatiquement.

D’autres fichiers plus complets :

tcharlss - Mise à jour :27 November 2014 at 15:47