Utiliser des plugins

De base, Pelican propose déjà pas mal de choses. Mais grâce à son système de plugins, il est possible de rajouter de nouvelles fonctionnalités à ce générateur de site en un clin d’œil.

Dans cette partie, je vous présenterais tout d’abord le principe de fonctionnement des plugins. Ensuite, je vous mentionnerais quelques plugins que je juge presque indispensable.

Généralités sur les plugins

reader ou generator, deux types de plugins

Dans écosystème Pelican, on trouve surtout deux types de plugins. L’un regroupe les readers (les lecteurs), et l’autre les generators (générateurs). Voyons les différences.

Les readers

Un reader est un plugin qui aura la charge de prendre un document en entrée pour le transformer en un nouveau format. Par exemple, un plugin qui permet de rédiger en LaTeX tombera dans cette catégorie. En effet, il aura la tâche de transformer un nouveau format d’entrée (le LaTeX) en html, le format des pages web. Le reader a deux tâches principales. La première, identifier et regrouper les métadonnées du contenu afin qu’elles soient utilisable dans les templates. La seconde est bien entendu la transformation du contenu réelle de l’article en html.

Les generators

Les générateurs ont aussi pour but de créer de nouvelles pages, mais pour cela il ne partent pas d’un seul fichier source mais plutôt de l’ensemble de votre site. Par exemple, le plugin "sitemap" que nous allons voir dans ce chapitre permet, à partir de l’ensemble des pages générées, de créer un fichier sitemap.xml qui regroupe le plan de votre site, bien utile pour les outils d’indexation des moteurs de recherche et autres robots.

Comment installer un plugin

Installer un plugin est relativement trivial. Il suffit tout simplement de télécharger ce dernier, le mettre au bon endroit puis régler sa configuration. Voyons cela.

Trouver un plugin

Pour cela rien de plus simple, la majeur partie des plugins (si ce n’est la totalité) se trouve sur le dépôt git suivant : https://github.com/getpelican/pelican-plugins .

Une fois le plugin qui vous intéresse identifié, il ne reste plus qu’à le récupérer. Deux cas de figures peuvent alors se présenter. Soit le plugin est dans un sous-module git, et dans ce cas il suffit de cloner uniquement ce sous-module. Soit le plugin est directement dans le dossier. Dans ce cas, je vous conseille de passer par l’outil DownGit pour récupérer juste le dossier qui vous intéresse.

Installer le plugin

Passons maintenant à l’installation d’un plugin.

Tout d’abord, je vous propose de créer un dossier nommé plugins à la racine de votre dossier de travail (donc au même niveau hiérarchique que le dossier content).

Ensuite, il va falloir informer Pelican que nos plugins vont se trouver dans ce dossier. Il faut pour cela ajouter une ligne dans le fichier de configuration pelicanconf.py :

PLUGIN_PATHS = ["plugins"]

Cette ligne contient simplement un tableau de tout les dossiers que Pelican va explorer pour trouver des plugins.

Enfin, vous l’avez peut-être deviné, il va falloir copier/déplacer les plugins précédemment téléchargé pour les mettre dans ce fameux dossier plugins/ que nous venons de créer.

Il ne reste plus qu’à activer ou non les plugins pour les voir rentrer en action. Une simple ligne dans le fichier de configuration fait ce travail :

PLUGINS = ["sitemap", "subcategory", "permalink"]

Là encore, c’est un tableau contenant les noms des dossiers des plugins à utiliser tels qu’ils sont nommés dans le dossier plugins/.

De manière général, pour obtenir plus d’informations sur les plugins la page de référence se trouve ici : http://docs.getpelican.com/en/stable/plugins.html .

Une extension pour générer un sitemap

Afin de voir comment fonctionne les plugins, je vous propose d’en étudier deux : sitemap et subcategory. Commencons par sitemap dans cette partie.

Installer sitemap

Ce premier plugin permet de générer une page de type sitemap. c’est le type de page qui permet d’inventorier les pages accessibles pour les moteurs de recherche notamment. C’est donc plutôt utile si vous êtes sensible à la visibilité de votre site sur internet. En général, cela consiste en un fichier au format xml regroupant les pages ainsi que leur date de dernière mise à jour.

Trêve de bavardage, récupérons tout de suite le plugin (via DownGit) à l’adresse suivante : https://github.com/getpelican/pelican-plugins/tree/master/sitemap .

Une fois que vous l’avez sur votre disque dur, il vous faudra le déplacer dans le dossier plugin de votre site internet comme vu précédemment. Enfin, il ne reste plus qu’à l’activer en l’ajoutant à la constante PLUGINS du fichier de configuration pelicanconf.py.

PLUGINS = ["sitemap"]

Paramétrer le plugin

Comme de très nombreux plugins, sitemap propose des options de configuration. Si vous ne faites rien, il fonctionnera de base très bien. Mais pour des utilisateurs ayant des besoins plus spécifiques, quelques options sont réglables. Ces dernières sont résumé dans le fichier Readme du plugin.

La première option est le format du fichier généré. Par défaut, ce sera du xml, mais un format texte brut (txt) est aussi possible. Pour choisir, il faut ajouter une nouvelle ligne dans le fichier de configuration pelicanconf.py. Cette nouvelle ligne sera une constante du nom de SITEMAP et contiendra un dictionnaire des différents paramètres à modifier. Donc pour régler le format de sortie, on obtiendra la ligne suivante :

# Pour passer au format txt plutôt que xml
SITEMAP = {
    'format': 'txt'
}

Sitemap propose aussi d’exclure des urls pour limiter leur indexation. Cela se fait avec le paramètre exclude suivi d’un tableau des adresses à supprimer. Par exemple pour ne pas proposer les pages de tags et de catégories, on modifierai la donnée de la manière suivante :

SITEMAP = {
    'format': 'txt',
    'exclude': ['tag/', 'category/']
}

Un dernier paramètre intéressant à paramétrer est la fréquence de changement des contenus. Si vos contenus sont susceptibles de changer fréquemment, autant prévenir les moteurs de recherches pour qu’ils reviennent plus souvent voir les différences. Les fréquences possibles sont always (toujours en changement), hourly (toutes les heures), daily (tous les jours), weekly (hebdomadaire), monthly (mensuel), yearly (annuel) et never (ne changera jamais). Ces paramètres peuvent être appliqués aux articles, aux pages ou encore aux indexes (les pages de listes par exemple). Pour cela, on ajoute un dictionnaire à nos données :

SITEMAP = {
    'format': 'txt',
    'exclude': ['tag/', 'category/'],
    'changefreqs': {
        'articles': 'daily',
        'pages': 'monthly',
        'indexes': 'daily'
    }
}

Comme dis plus haut, toutes ces configurations sont facultatives, celle par défaut feront sûrement très bien le travail dans la plupart des cas.

Si jamais vous voulez en savoir plus ou voir les quelques paramètres restants, n’hésitez pas à consulter le Readme dans votre dossier d’installation ou en ligne.

Une extension pour créer des sous-catégories

Afin de clôturer ce chapitre avec de bonne idées, voici une deuxième extension que j’affectionne : subcategory. Comme son nom l’indique, elle permet de regrouper les contenus en catégories et sous-catégories. Par exemple, on pourrait avoir une catégorie "Dessert" qui regrouperait des sous-catégories "gâteaux", "cookies", "crèmes" …

Comme pour le plugin précédent, ce dernier est disponible dans le dépôt principal de pelican-plugins à l’adresse suivante : https://github.com/getpelican/pelican-plugins/tree/master/subcategory . Là encore, il faudra le déplacer dans le dossier plugins/ de votre site web puis l’ajouter à la ligne PLUGINS de la configuration :

PLUGINS = ["sitemap", "subcategory"]

Maintenant, pour l’utiliser c’est très simple. Il suffit simple d’éditer la métadonnée Category de vos contenus. Par exemple, pour qu’un article soit automagiquement classé dans la catégorie "Dessert/Gateaux" on fera simplement Category: Dessert/Gateaux (le caractère / sert de séparateur). Vous pourrez maintenant assez simplement faire un fil d’ariane dans vos template en utilisant nouvelle variable subcategories. Par exemple :

<ol>
    <li><a href="/{{ article.category.url }}">{{ article.category}}</a></li>
    {% for subcategory in article.subcategories %}
        <li class="breadcrumb-item"><a href="/{{ subcategory.url }}">{{ subcategory.shortname }}</a></li>
    {% endfor %}
    <li class="breadcrumb-item active" aria-current="page">{{ article.title }}</li>
</ol>

Là encore, quelques paramètres sont disponibles, surtout lié aux chemins d’enregistrement des fichiers. Ceux par défaut sont de nouveaux très bien. Je vous laisse les consulter dans le README, à la section settings.

Vous savez maintenant comment ajouter des nouvelles fonctionnalités à votre générateur de site. Dorénavant, si une fonctionnalité vous manque, vous pourrez carrément la coder vous même afin d’enrichir votre contenu facilement. A ce sujet, j’avais de mon côté fait un plugin pour générer des pages à partir du format markdown utilisé sur Zeste de Savoir, le zmarkdown. Voici l’article à ce sujet.