Lundi 3 décembre 2018

Pelican (NON Installé)

Utiliser Pelican comme moteur de blog
Les générateurs de site Web statiques, et mon choix de Pelican
Pelican: un générateur de sites statiques
Pelican est un outil Python pour générer des pages HTML à partir de contenus textes structurés (formats ReST, Markdown, Org). Vous écrivez déjà vos README en Markdown sur Github, pourquoi pas vos articles de blog ?
Tout est d’ailleurs prévu dans Pelican pour construire un blog : il connaît la notion d’article, de brouillon, de page, de flux RSS et bien sûr de thème. Pour les templates, il utilise Jinja dont la syntaxe est très proche des templates Django.

Installer un domaine doc.ouestline.net
Certificats SSL

Site doc
Installer une application personnalisée Multi custom webapp https://github.com/YunoHost-Apps/multi_webapp_ynh
Libellé pour Multi custom webapp : Doc
Choisissez un domaine pour votre Webapp : doc.ouestline.net
Choisissez un chemin pour votre Webapp : / (il ne sera plus possible d’ajouter quoique ce soit à ce domaine)
Choisissez l’utilisateur YunoHost associé : yan spm
Créer une base de données? : Non (ne pas cocher la case)
Est-ce un site public ? : Non (Ne pas cocher la case)
Vous ne pourrez pas installer d’autres applications sur doc.ouestline.net. Continuer ? OK

Installer aplication Pelican : https://github.com/YunoHost-Apps/pelican_ynh

Dossier /var/www/pelican

Using Themes https://github.com/getpelican/pelican-themes
These instructions assume you have already read all the Pelican documentation, have a working site, and would now like to apply a non-default theme.

First, choose a location to hold your themes. For this example, we’ll use the directory ~/pelican-themes, but yours could be different. Clone the pelican-themes repository to that location on your local machine:
git clone --recursive https://github.com/getpelican/pelican-themes ~/pelican-themes
Now you should have your pelican-themes repository stored at ~/pelican-themes/.

To use one of the themes, edit your Pelican settings file to include this line:
THEME = "/home/user/pelican-themes/theme-name"

So, for instance, to use the bootstrap2 theme, you would edit your settings file
sudo nano /var/www/pelican/pelicanconf.py
to include:
THEME = "/home/yann/pelican-themes/bootstrap2"

Save the changes to your settings file and then regenerate your site by using the Makefile you should already have set up using pelican-quickstart:
sudo -s && cd /var/www/pelican && make html

Themes can also be specified directly via the -t ~/pelican-themes/theme-name parameter to the pelican command. If you want to edit your theme, make sure that any edits you make are made to the copy stored in ~/pelican-themes/theme-name. Any changes made to files stored in your site’s output directory will be deleted the next time you generate your site.

Pelican sur debian (générateur site statique)

Languages:Python
Templates:Jinja2
License:AGPL v3.0

Python Pip

Pip est un système de gestion de paquets utilisé pour installer et gérer des librairies écrites en Python . Vous pouvez trouver une grande partie de ces librairies dans le Python Package Index (ou PyPI). Pip empêche les installations partielles en annonçant toutes les exigences avant l’installation.

Pour installer pip il vous faudra exécuter la commande:

sudo apt-get install python-pip

Pip vous permet d’installer une librarie aussi facilement que cela:

pip install django

Facile!

Vous pouvez choisir la version qui vous intéresse:

pip install django==2.2

Supprimer une lib:

pip uninstall django

Mettre à jour une lib:

pip install django --upgrade

Downgrader une version:

pip install django==2.1 --upgrade

Rechercher une nouvelle lib

pip search django

Vous indique quels lib n’est plus à jour:

pip list --outdated

Affiche toutes les lib installées et leur version

pip freeze

Si vous exportez cette liste, vous pouvez la réimporter ailleurs:

pip freeze > lib.txt

Puis vous l’importez comme ceci:

pip install -r lib.txt

Pour créer un gros zip qui contient toutes les dépendances:

pip bundle <nom_du_bundle>.pybundle -r lib.txt

Puis pour installer les lib

pip install <nom_du_bundle>.pybundle

Environnement Pelican (virtualenv)

https://zestedesavoir.com/tutoriels/2497/creer-un-site-web-statique-avec-pelican/presentation-de-pelican/pelican-comment/

Prérequis

  • python pip : sudo apt install python-pip
  • virtualenv : sudo apt install python-virtualenv

Pelican ,il suffit d’installer seulement deux paquets, pelican et Markdown.On va toutefois travailler proprement dans un environnement virtuel.

Je vais donc commencer par créer ce dernier puis l’activer. Je travaillerai dans le dossier “pelican-static”.

mkdir pelican-static
cd pelican-static
virtualenv venv
source venv/bin/activate # nouveau prompt : (venv) dbsuser@dbs:~/pelican-static$
pip install pelican Markdown

Et voilà, Pelican est maintenant installé !!
Maintenant que les outils sont là, vérifions que tout marche avant de nous lancer à l’assaut de notre propre site !
Pour cela, Pelican met à disposition un outil de démarrage sous la forme d’une commande :

pelican-quickstart.
Welcome to pelican-quickstart v3.7.1.

This script will help you create a new Pelican-based website.

Please answer the following questions so this script can generate the files
needed by Pelican.

    
> Where do you want to create your new web site? [.] 
> What will be the title of this web site? Static Pelican
> Who will be the author of this web site? yannick
> What will be the default language of this web site? [fr] 
> Do you want to specify a URL prefix? e.g., http://example.com   (Y/n) 
> What is your URL prefix? (see above example; no trailing slash) static.ouestline.net
> Do you want to enable article pagination? (Y/n) 
> How many articles per page do you want? [10] 
> What is your time zone? [Europe/Paris] 
> Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n) 
> Do you want an auto-reload & simpleHTTP script to assist with theme and site development? (Y/n) 
> Do you want to upload your website using FTP? (y/N) 
> Do you want to upload your website using SSH? (y/N) 
> Do you want to upload your website using Dropbox? (y/N) 
> Do you want to upload your website using S3? (y/N) 
> Do you want to upload your website using Rackspace Cloud Files? (y/N) 
> Do you want to upload your website using GitHub Pages? (y/N) 
Done. Your new project is available at /home/dbsuser/pelican-static

Enfin exécutez la commande

pelican

le terminal vous répondra qu’aucun article n’a été généré (c’est normal) avec les lignes suivantes :

WARNING: No valid files found in content.
Done: Processed 0 articles, 0 drafts, 0 pages and 0 hidden pages in 0.05 seconds.

Configuration nginx

sudo ln -s /home/dbsuser/pelican-static/output /var/www/pelican  #le lien

/etc/nginx/conf.d/

server {
    listen 80;
    listen [::]:80;

    ## redirect http to https ##
    server_name static.ouestline.net;
    return  301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;

    server_name static.ouestline.net;
    root /var/www/pelican/ ;

    ssl_certificate /etc/ssl/private/ouestline.net.fullchain.cer.pem;
    ssl_certificate_key /etc/ssl/private/ouestline.net.key.pem;
    ssl_session_timeout 5m;
    ssl_session_cache shared:SSL:50m;

    # As suggested by Mozilla : https://wiki.mozilla.org/Security/Server_Side_TLS and https://en.wikipedia.org/wiki/Curve25519
    # (this doesn't work on jessie though ...?)
    # ssl_ecdh_curve secp521r1:secp384r1:prime256v1;

    # As suggested by https://cipherli.st/
    ssl_ecdh_curve secp384r1;

    ssl_prefer_server_ciphers on;

    # Ciphers with modern compatibility
    #---------------------------------
    # https://mozilla.github.io/server-side-tls/ssl-config-generator/?server=nginx-1.6.2&openssl=1.0.1t&hsts=yes&profile=modern
    # Uncomment the following to use modern ciphers, but remove compatibility with some old clients (android < 5.0, Internet Explorer < 10, ...)
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers 'TLS13+AESGCM+AES128:EECDH+AESGCM:EECDH+CHACHA20:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256';

    # Uncomment the following directive after DH generation
    # > openssl dhparam -out /etc/ssl/private/dh2048.pem -outform PEM -2 2048
    #ssl_dhparam /etc/ssl/private/dh2048.pem;

    # Follows the Web Security Directives from the Mozilla Dev Lab and the Mozilla Obervatory + Partners
    # https://wiki.mozilla.org/Security/Guidelines/Web_Security
    # https://observatory.mozilla.org/ 
    add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload"; 
    add_header Content-Security-Policy "upgrade-insecure-requests";
    add_header Content-Security-Policy-Report-Only "default-src https: data: 'unsafe-inline' 'unsafe-eval'";
    add_header X-Content-Type-Options nosniff;
    add_header X-XSS-Protection "1; mode=block";
    add_header X-Download-Options noopen;
    add_header X-Permitted-Cross-Domain-Policies none;
    add_header X-Frame-Options "SAMEORIGIN";

    index index.php;
        location ~ \.php$ {
           fastcgi_split_path_info ^(.+\.php)(/.+)$;
           fastcgi_pass unix:/run/php/php7.2-fpm.sock;    # PHP7.2 
           fastcgi_index index.php;
           include fastcgi_params;
           fastcgi_param SCRIPT_FILENAME $request_filename;
        }
}
sudo nginx -t
sudo systemctl restart nginx

Vous devriez voir cependant qu’un dossier output est rempli de fichiers. Ouvrez le fichier index.html avec votre navigateur favori et Tadddaaa, votre premier site web statique sous vos yeux !

Arborescence pelican

(venv) dbsuser@dbs:~/pelican-static$ tree -L 2
.
├── content
├── develop_server.sh
├── fabfile.py
├── output
│   ├── archives.html
│   ├── authors.html
│   ├── categories.html
│   ├── index.html
│   ├── tags.html
│   └── theme
├── pelicanconf.py
├── pelicanconf.pyc
├── publishconf.py
  • Le dossier content. En français “contenu”, c’est ici que nous placerons nos rédactions au format markdown.
  • develop_server.sh. L’outil d’aide au développement
  • Le dossier output. C’est ici que va se retrouver notre site internet final mis en forme.
  • Le fichier de configuration de Pelican pelicanconf.py, pour régler certains paramètres permettant de passer du contenu au rendu final.
  • Le fichier de configuration publishconf.py pour reparamètrer certains aspects.

entête du fichier

Le premier moyen mis à notre disposition (et le plus flexible) pour ajouter des données de contexte à notre article est de les placer avant le corps de notre contenu. Pour cela, il suffit de présenter les informations sous la forme d’une liste « clé:valeur », avec une donnée par ligne.

Données simples

En premier lieu, on trouve des données « simples », composées juste d’un texte. On trouve par exemple le titre, la description ou la catégorie de l’article :

Title: Mon superbe article
Summary: Voici un article absolument génial pour présenter les choses !
Category: Cookie

On trouve aussi des données qui doivent uniquement être en « un seul mot », donc avec les espaces représentés par des tirets (-) ou des underscores (_). C’est le cas notamment du slug cette chaîne représentant l’identifiant unique de l’article (qui est souvent extrapolé à partir du titre).

Title: Mon superbe article
Slug: mon-superbe-article

Des listes

On peut aussi rencontrer des listes, comme par exemple une liste de tags pour thématiser notre article ou encore une liste d’auteurs. Dans ce cas, le caractère de séparation sera la virgule

Tags: cuisine, dessert, cookies
Authors: Eskimon, Clementine Sanspepins, Jean Bonbeurre

Si jamais vos listes contiennent des textes avec des virgules, alors vous devez utiliser le ; comme séparateur.

Des dates

Afin d’informer les lecteurs de la fraîcheur de nos contenus, la date de publication est essentielle ! La date de modification peut elle aussi être utile. Les dates sont des contenus particuliers puisqu’elles doivent être rédigées sous une forme compatible avec le sous-ensemble ISO 8601. Les différents formats sont :

  • Année uniquement : AAAA (exemple : 2018)
  • Année et mois : AAAA-MM (exemple : 2018-06)
  • Date complète : AAAA-MM-JJ (exemple : 2018-06-04)
  • Date complète + heures et minutes : AAAA-MM-JJThh:mmTZD (exemple : 2018-06-04T15:28+01:00) (Attention au T séparant date et heure ainsi qu’à l’indicateur de timezone)
  • Date complète + heures, minutes, secondes : AAAA-MM-JJThh:mm:ssTZD (exemple : 2018-06-04T15:30:25+01:00)
  • Date complète + heures, minutes, secondes et une fraction de seconde : AAAA-MM-JJThh:mm:ss.sTZD (exemple : 2018-06-04T15:31:26.42+01:00)

Par exemple pour un article paru le 6 mai 2018 et mis à jour le 25 décembre 2018 :

Date: 2018-05-06
Modified: 2018-12-25

Le format horaire peut aussi être exprimé en UTC, dans ce cas il faut supprimer la partie ajoutant l’heure et mettre un Z à la place. Ainsi, 2018-06-04T15:28+01:00 devient 2018-06-04T14:28Z

Voici un aperçu des métadonnées les plus usuelles. Vous aurez remarqué qu’elles sont en anglais ;) . Si jamais vous souhaitez ajouter des données supplémentaires, vous être libre de le faire ! La seule condition est que la clé soit en un seul mot (par exemple une clé “lien canonique” pourrait être notée “lien_canonique”).

Seul le titre est obligatoire. Toutes les autres données seront extrapolées des données du fichier lui-même si jamais elles sont absentes. Voyons cela.

Via le contexte du fichier

Comme expliqué un peu plus tôt, seul le titre (Title) est obligatoire. Le reste est alors lu à partir des données du fichier et sous couvert que le fichier de configuration pelicanconf.py est bien paramêtré. Voyons cela.

Date de l’article

Si aucune date n’est présente dans les metadonnées, alors ce sera la date de création du fichier qui sera prise en compte. Il faut pour cela que le paramètre de configuration DEFAULT_DATE ai pour valeur fs (signifiant filesystem).

'DEFAULT_DATE' = 'fs'

Le champ Modified n’exploite pas les données du fichier. Il aura la même valeur que Date s’il n’est pas précisé.

La catégorie

La catégorie de l’article (Category) peut-être devinée via le chemin du fichier. Un document “choco-banane.md” situé dans le dossier “cookie” (content/cookie/choco-banane.md) sera alors rangé dans la catégorie “cookie”.

Si jamais le paramètre de configuration USE_FOLDER_AS_CATEGORY est à False alors le champ DEFAULT_CATEGORY prend le relais.

Slug et autres

Le nom du fichier peut-être paramétré pour retirer des données. Par exemple on pourrait vouloir que le nom de notre fichier soit aussi le slug de l’article. Pour cela, il faut régler le paramètre FILENAME_METADATA de façon à décrire “où” sont les données dans le fichier. Si par exemple le fichier s’appelle 2018-05-06_de-bons-cookies.md et que FILENAME_METADATA = ‘(?P\d{4}-\d{2}-\d{2})_(?P.*)', pelican automatiquement pourra sortir la date au format AAAA-MM-JJ puis le slug.

Summary

Le champ Summary quant à lui exploitera directement le début de l’article pour se former automatiquement s’il n’est pas spécifié. Un paramètre de configuration, SUMMARY_MAX_LENGTH, permet de régler le nombre de mots du début de l’article seront utilisé pour construire le résumé.

Dernière information importante, les données précisé dans l’entête de l’article ont toujours la priorité.

Vous avez maintenant toutes les cartes en mains pour paramétrer vos articles, il ne restent plus qu’à les écrire ! Pour cela, le prochain chapitre vous propose d’aller à la découverte des différents formats vous permettant de rédiger.

Markdown

Le premier moyen de rédaction que je souhaite vous présenter est le markdown. Pour l’utiliser il faudra que vos fichiers aient l’extension .md (les extensions .markdown, .mkd ou .mdown sont aussi acceptées). Aussi, le parseur markdown doit-être installé via la commande pip install markdown.

Markdown est un format de rédaction très agréable à utiliser car son markup est très léger, ce qui fait qu’un document rédigé mais non mis en forme reste tout de même très lisible.

La syntaxe des métadonnées lorsque l’on utilise le format markdown est celle que l’on a vu dans le chapitre précédent, à savoir une liste de clé:valeur.

Title: Ma super recette de cookies
Date: 2018-06-06 09:00
Modified: 2018-06-07 14:42
Category: Cookie
Tags: cookie, chocolat, recette
Slug: ma-super-recette-de-cookies
Authors: Eskimon
Summary: Dans cette article je vous présente une recette pour des cookies délicieux !

Voici le corps de l'article, blablabla...

reStructuredText - .rst

Le format reStructuredText possède quant à lui l’extension .rst. Il ne nécessite pas l’installation d’un package supplémentaire particulier. Pour ceux qui l’ignore, c’est le langage utilisé pour la rédaction de la documentation de python !

Là encore, au delà des sucres syntaxiques, tout se joue dans l’organisation des métadonnées. On retrouve de nouveau une liste de clé:valeur au format :clé:valeur (: avant la clé). Regardez bien l’exemple suivant, le titre lui aussi change d’aspect.

Ma super recette de cookies
###########################

:Date: 2018-06-06 09:00
:Modified: 2018-06-07 14:42
:Category: Cookie
:Tags: cookie, chocolat, recette
:Slug: ma-super-recette-de-cookies
:Authors: Eskimon
:Summary: Dans cette article je vous présente une recette pour des cookies délicieux !

Voici le corps de l'article, blablabla...

Hypertext Markup Language - .html

Le dernier langage utilisable lui aussi sans extension est le HTML. Indispensable pour faire des pages web, il permet aussi de rédiger directement vos articles. Il est cependant bien plus verbeux que les deux précédents que nous venons de voir.

Pour l’utiliser, il faudra que les fichiers des articles aient l’extension .html ou .htm. Ensuite, il suffit d’imaginer rédiger une page web classique, en se contentant du strict minimum. On trouve alors les metadonnées dans la balise <head> et le corps de l’article dans <body>. Le tout étant englobé d’une balise <html>.

Voici notre exemple de nouveau :

<html>
    <head>
        <title>Ma super recette de cookies</title>
        <meta name="tags" content="cookie, chocolat, recette" />
        <meta name="date" content="2018-06-06 09:00" />
        <meta name="modified" content="2018-06-07 14:42" />
        <meta name="category" content="Cookie" />
        <meta name="authors" content="Eskimon" />
        <meta name="summary" content="Dans cette article je vous présente une recette pour des cookies délicieux !" />
    </head>
    <body>
        Voici le corps de l'article, blablabla...
    </body>
</html>

Voilà cette rapide présentation faite. Comme vous pouvez vous en doutez, bien que la rédaction aura un aspect différent dans le document brut, le rendu sera quant à lui le même.

Si jamais vous souhaitez utiliser un autre format de rédaction, il existe de nombreux plugins ajoutant ces fonctionnalités. Veillez à bien consulter leur documentation, la mise en forme des métadonnées peut changer d’un article à l’autre. Pour ceux voulant aller plus loin, j’avais même fait un billet traitant de l’ajout du zmarkdown dans Pelican pour pouvoir rédiger avec le même markdown que celui de Zeste de Savoir !