Narval est un générateur de blog statique écrit en Python. Il s’utilise avec le terminal et ne dispose que d’une seule ligne de commande permettant la génération d’un blog. Le principe est simple :

1. tous les fichiers utiles au blog sont dans un dossier;
2. Narval, en une ligne de commande, convertit le contenu de ce dossier en blog;
3. Ce blog est alors disponible en 2 versions (une pour en avoir un aperçu sur son ordinateur et une autre à mettre en ligne).

Le guide rapide de Narval permet une bonne entrée en matière. Cette documentation est plus poussée et reprend en détail chaque point du guide rapide.

Sommaire

• Avant l’installation
• Installation
  
  • En ligne de commande
  • Via le site Github
• Arborescence du dossier
  
  • core/ et build.py
  • content/
    
    • CONFIG
    • attachments/
    • pages/
    • posts/
    • templates/
    • themes/

Avant l’installation

Narval est écrit en Python 3.

Les modèles de pages (appelés templates dans la suite du document) sont écrits à l’aide de Tenjin, un moteur de templates qui combine de façon simple et claire du HTML et du Python. Il existe d’autres moteurs de templates comme le très connu Jinja2 par exemple, mais Tenjin a l’avantage d’être le plus rapide à l’exécution.

Narval nécessite donc Python (version 3 ou supérieure). Cette commande dans un terminal permet de savoir s’il est déjà présent sur l’ordinateur :

python -V

Si un numéro de version apparaît et qu’il est supérieur à 3, c’est que c’est bon ! Sinon, il faut installer Python.

Tenjin s’installe facilement avec cette ligne de commande :

sudo easy_install Tenjin

Si besoin, il est aussi possible de voir comment l’installer sur ce site.

Installation

Narval se trouve sur Github et peut s’installer de 2 façons.

En ligne de commande

Cette méthode nécessite Git. Git est également utile pour versionner un projet et le mettre en ligne sur Github Pages par exemple. Github permet d’héberger gratuitement son site statique et justement, Narval génère ce genre de site. Si Git est déjà installé, son numéro de version apparaît lorsque tu saisis dans un terminal :

git --version

Sinon, il te faudra l’installer. Cette page indique la marche à suivre.

Une fois Git présent dans ton ordinateur, tu peux installer Narval avec cette ligne de commande :

git clone https://github.com/narvalblog/narval

Cette commande télécharge Narval depuis Github. Le dossier reçu contient Narval (le générateur) ainsi que les dossiers et fichiers permettant de générer le blog de démonstration.

Via le site Github

En suivant ce lien, puis en cliquant sur « Clone or download » (bouton vert en haut de page) et enfin en cliquant sur « Download ZIP ». Une fois l’archive téléchargée, il faut la décompresser. Le dossier contient Narval (le générateur) ainsi que les dossiers et fichiers permettant de générer le blog de démonstration.

Arborescence du dossier

Allons faire un tour dans le dossier narval/. Il s’y trouve 2 dossiers (content/ et core/) ainsi que quelques fichiers dont le seul qui est primordial au fonctionnement de Narval est build.py.

core/ et build.py

build.py est le fichier principal du générateur de blog. Il fonctionne avec le dossier core/ qui contient le reste du programme. core/ et build.py ne doivent pas subir de modifications personnelles afin que lorsque Narval est mis à jour sur Github et que tu souhaites migrer vers cette mise à jour, ton blog continue de fonctionner correctement. Si tu souhaites changer quelques chose à l’intérieur de ces fichiers et dossiers, tu peux participer au développement de Narval sur Github et proposer tes modifications.

content/

Le dossier content/ regroupe tous les fichiers et dossiers qui seront incorporés sous une forme ou une autre dans le blog final. Passons en revue chaque élément de content/.

CONFIG

Contient la configuration du blog. Il s’agit d’un fichier composé de clefs et valeurs. La syntaxe nécessite un peu de rigueur :

• une ligne par clef: valeur;
• aucune ligne vide;
• la clef est séparée de la valeur par “:”;
• la valeur est toujours un texte non mis entre guillemets.

Voici la liste des clefs acceptées par ce fichier :

• url : l’adresse où sera consultable le blog. Cette adresse est en général celle d’un serveur distant (sur Internet) et commence par http:// (ou, de préférence, https://);
• title : Le titre du blog. Ne peut contenir de code HTML;
• subtitle : Le sous-titre du blog.
• date : La date à laquelle le blog voit le jour pour la première fois. Elle doit être au format ISO 8601. Voici quelques exemple de date acceptés : 2017-07-10 (pour le 10 juillet 2017), 2017-07-10 20:32 ou 2017-07-10T20:32 (pour le 10 juillet 2017 à 20h32). Il est également possible d’indiquer les secondes, les millisecondes et le fuseau horaire pour une date vraiment complète (mais peu utile). Par exemple : 2017-07-10T20:32:16.002645+02:00 pour la même date que précédemment, mais avec en plus 16 secondes, 002645 millisecondes et un fuseau horaire de + 2 heures par rapport au méridien de Greenwich;
• description : La description du blog. Ne peut contenir de code HTML;
• itemsbypage : Le nombre maximal d’articles à afficher par page;
• folder : Le nom du dossier où se situera le blog généré et à mettre en ligne (sans ‘/’);
• author : Le nom de l’auteur·e principal·e du blog;
• theme : Le nom du dossier qui contient le thème à afficher pour le blog (sans ‘/’);
• template : Le nom du dossier qui contient les templates à afficher pour le blog (sans ‘/’);
• lang : La langue principale du blog. Les seules valeurs possibles sont actuellement en (pour anglais) et fr (pour français);
• disqus : Un identifiant provenant de Disqus permet d’afficher un système de commentaire pour chaque article du blog.

Une clef peut ne pas contenir de valeur. Une clef sans valeur peut être retirée du fichier. Quand une clef manque, Narval tente d’en définir une ou attribue à la clef une valeur par défaut. Par exemple, si la clef itemsbypage est sans valeur ou manquante, par défaut, itemsbypage vaudra 10 et un maximum de 10 articles par page sera affiché. Si une autre valeur que en ou fr est indiquée pour lang, fr sera appliquée par défaut. Si une paire clef-valeur est manquante et indispensable, un message d’erreur indiquant le problème apparaîtra lors de la génération du blog.

attachments/

Ce dossier regroupe toutes les pièces jointes des articles et des pages du blog (images, sons, vidéos, fichiers à télécharger, etc.). Il peut être organisé en sous-dossiers si besoin.

pages/

Ce dossier regroupe les pages du blog et 2 fichiers optionnels : CATEGORIES et AUTHORS. Comme le fichier CONFIG, ces fichiers contiennent des clefs et des valeurs. CATEGORIES et AUTHORS contiennent respectivement les différentes catégories et les différent·e·s auteur·e·s des pages, séparé·e·s d’une ligne vide.

Ce dossier doit également contenir un dossier nommé draft qui contient des brouillons. Il s'agit de pages accessibles uniquement depuis leurs URLs. Elles ne seront pas référencées. Ce blog de démonstration contient un brouillon accessible à cette adresse : https://narvalblog.github.io/exemple-de-brouillon.html.

Voici la liste des clefs d’une catégorie figurant dans CATEGORIES :

• title : Le titre de la catégorie;
• slug : Chemin d’accès, dans l’URL, permettant d’accéder à la liste des pages de la catégorie. Ce nom ne doit comporter des lettres non accentuées en minuscule, des chiffres, des tirets - et des underscores _;
• description : La description de la catégorie. Sans code HTML;
• definition : La définition de la catégorie. Peut contenir du code HTML;
• template : Indique le nom du dossier où se trouve des pages de templates particulières (elles remplacent des templates par défaut);
• color : Indique une couleur en un format accepté par le CSS (rgb, rgba, hexadécimal (avec le #) ou un nom existant). Dans les templates de Minimal, elle s’affiche dans le menu en haut de page et sous le titre de chaque page disposant d’une catégorie;
• image : L’image représentant la catégorie. Les templates et le thème de Minimal ne prennent pas en charge l’affichage de cette image. Mais il est possible de l’incorporer.

AUTHORS accepte certaines des clefs de CATEGORIES : slug, description et image. Les autres clefs sont :

• name : le nom ou pseudonyme de la personne;
• mail : l’adresse de messagerie électronique de la personne;
• website : l’adresse URL du site web de la personne;
• biography : la biographie de la personne.

Tout autre fichier est considéré comme étant une page du blog. Chaque fichier porte le nom que l’on souhaite lui donner. L’extension peut être :

• .htm, .html : si le contenu de la page est écrit en HTML;
• .md, .markdown : si le contenu de la page est écrit en Markdown.

L’extension permet de convertir le contenu avec un langage de balisage particulier (ceux de la liste ci-dessus) en HTML (car l’affichage de texte formaté sur Internet se fait en HTML). Dans le cas d’un contenu en HTML, il n’y a pas conversion. Attention : si l’extension indique un contenu en HTML et qu’il n’en est rien, il n’y a pas conversion.
Si tu souhaites écrire tes pages avec du Markdown, il est nécessaire d’installer préalablement la dépendance nécessaire à la conversion :

sudo easy_install markdown

Ou (si pip est installé) :

sudo pip install Markdown

Sur Windows, je recommande de consulter cette page pour l’installation.

Le contenu d’un fichier de type page se divise en 2 parties séparées par une ligne vide : des paires clef-valeur et le contenu de la page.

Voici la liste des clefs :

• title : Le titre de la page (peut contenir du HTML);
• date : La date de publication ou de rédaction de la page au format ISO 8601 (pour les détails, voir ici);
• modified : La date à laquelle la page a été modifiée (format identique à la clef Date);
• slug : Chemin d’accès, dans l’URL, permettant d’accéder à la liste des pages de la catégorie. Ce nom ne doit comporter des lettres non accentuées en minuscule, des chiffres, des tirets - et des underscores _;
• categories : La ou les catégories à laquelle la page appartient. Elles sont à séparer par le signe +. Exemple : photographie + Art + Tutoriel;
• description : La description de la page (sans HTML);
• introduction : Le texte qui introduit la page (peut contenir du HTML);
• authors : La ou les personnes ayant rédigées la page. Comme pour la clef Categories, le signe + sépare les auteur·e·s;
• image : L’image qui illustre la page;
• template : Le dossier du template à utiliser pour la page s’il est particulier.

posts/

Similaire au dossier pages/, posts/ contient les articles du blog et 2 fichiers optionnels : CATEGORIES et AUTHORS. Un article dispose des mêmes clefs qu’une page, car tout simplement, il constitue également une page. Voir la section pages/.

templates/

Ce dossier contient des templates organisés sous forme de dossiers. Les templates sont fortement liés au thèmes. Chaque template se compose de plusieurs fichiers portant l’extension .pyhtml. Le moteur de template utilisé par Narval est Tenjin. Tenjin dispose de sa propre documentation. Le principal à retenir pour son utilisation avec Narval est mentionné ci-dessous :

• afficher une clef (sans HTML permis) : {=blog.subtitle=};
• afficher une clef (avec HTML permis) : {==blog.subtitle==};
• afficher une clef sans HTML : {=blog.rmHTML(blog.subtitle)=};

subtitle est une clef qui se trouve dans le fichier CONFIG. En admettant que sa valeur soit Mon <strong>super</strong> blog :

• {=blog.subtitle=} donne Mon <strong>super</strong> blog;
• {==blog.subtitle==} donne Mon **super** blog;
• {=blog.rmHTML(blog.subtitle)=} donne Mon super blog.

Pour itérer l'affichage des éléments d'une liste , il convient d’utiliser une boucle for. Cela se fait ainsi :

:: for post in blog.posts.list:
    <p>{==post.title==}</p>
:: #endfor

Ce code affiche les titres de tous les articles du blog.

Nous avons vu rapidement plus haut la fonction utilitaire rmHTML() qui supprime le code HTML d’un texte. Narval dispose d’une seconde fonction utilitaire convertDate() qui, comme son nom l’indique, permet de convertir une date. Voyons en détail ces deux fonctions simples :

rmHTML(text, md) :

• text est une chaîne de caractère contenant du HTML;
• md est un booléen. Si sa valeur est True, alors les marques HTML <strong>, <em> et <code> seront remplacées par leurs équivalents en Markdown. Cela est intéressant pour le fichier README que Narval génère (via readme.pyhtml). Par défaut md vaut False.

Exemples :

{=blog.rmHTML("Texte en <strong>gras</strong>", True)=} donne Texte en **gras**.

{=blog.rmHTML("Texte en <strong>gras</strong>")=} donne Texte en gras.

convertDate(dateISO, format) :

• dateISO est une date au format ISO 8601. Toutes les clefs Date et Modified sont de ce format;
• format est une chaîne de caractère particulière qui permet d’afficher la date au format ISO sous la forme voulue. Pour voir comment former sa propre date, il suffit de regarder cette documentation.

Exemples :

{=blog.convertDate("2017-07-26", "%B %Y)=} donne Juillet 2017.

Les fonctions utilitaires s’utilisent avec les clefs de Narval (autrement, autant écrire directement ce que l’on souhaite). On aura donc :

{=blog.convertDate(blog.modified, "%B %Y)=} donne Juillet 2017 si blog.modified vaut par exemple 2017-07-31.

themes/

Ce dossier regroupe tous les thèmes du blog.