Version 7 — Novembre 2014 — tcharlss
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.
Pour les articles documentant 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.
----
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.
Il faut avant tout déjà installer le plugin markdown pour SPIP. Il est sur la zone, mais il n’est pas référencé dans les dépôts, il faut donc le récupérer par SVN ou autre : http://zone.spip.org/trac/spip-zone/browser/_plugins_/markdown
Pour rappel , dans le texte d’un article on met soit le texte markdown entre balises < code><md >... , soit le texte spip entre balises <spip>...
</spip> selon la configuration.
<emb>
pour les fichiers markdownMaintenant, il nous faut une variante du modèle emb.html
du (du plugin Médias ) qui sera utilisée utilisé automatiquement avec pour les fichiers Markdown markdown . Le modèle de base regarde s’il existe une variante pour chaque extension , cherche des variantes de la forme emb_{extension}.html
, on va donc créer un nouveau squelette nommé emb_md.html
.Où placer ce squelette ? Logiquement il aurait sa place dans le plugin Markdwon me semble-t-il, mais pour les tests, le dossier des squelettes fera l’affaire.
Dans notre squelette, la balise [(#FICHIER|contenu_document)]
(ou
[(#ID_DOCUMENT|contenu_document)]</code Dans notre squelette , <code>#FICHIER|contenu_document</code > (ou < code>#ID_DOCUMENT|contenu_document</code >) récupère le contenu du fichier texte.
On fait Ensuite , il faut faire en sorte qu'il soit traité par de placer le parseur Markdown en le plaçant texte récupéré entre des balise <code><span class="base64mdblocs" title="PG1kPi4uLjwvbWQ+"></span>
, au moyen du filtre |wrap{<md>}
.
Ainsi, il sera pris en compte par le parseur markdown.
Après ça, un coup de |propre
et le tour est joué.
Ce qui donne au final, en ne gardant que l’essentiel :
<BOUCLE_tous (DOCUMENTS types_documents) {id_document=#ID} {tout}
>[(#FICHIER|contenu_document{#ENV{charset,auto}}|wrap{'<md>'}|propre)]</BOUCLE_tous>
A noter : on n’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.
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.
Ajoutons cette extension dans la table spip_documents_types
. C’est notamment là qu’on indique qu’il s’agit d’un type de document qu’on peut intégrer dans le texte, ce qui va nous permettre d’utiliser la balise <emb>
.
extension | titre | descriptif | mime_type | inclus | upload | media_defaut |
---|---|---|---|---|---|---|
md | Markdown document | texte/x-markdown texte/plain | embed | oui | file |
Pour bien faire , il faudrait À noter é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.php qui liste les différents types de fichiers, mais j’ignore son utilité et il ne semble pas avoir d’incidence sur notre problème.
----
Voilà, à partir de là ça devrait marcher.
On peut tester Par exemple en ajoutant par exemple quelques prenant les fichiers de tests du plugin markdown comme en 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 :