====== Pelican ======
<WRAP center round important 60%>
Notes personnelles, selon mon avancement la compréhension du fonctionnement de Pelican.
</WRAP>

Notes d'installation du générateur de sites statiques [[https://getpelican.com|Pelican]]. On me l'a conseillé parce que Python, parce que simple pour les idiots qui n'ont pas envie de se prendre le chou avec Hugo ou Jekyll.

Notes suite à une installation pour test sur un conteneur Debian 12 sous Proxmox.

===== Installation =====
On installe pip, Python3 était déjà installé sur mon conteneur Debian : 
<code bash>
apt install python3-pip -y
</code>

==== Définir une environnement virtuel Python ====

=== Sous Linux ===
<code bash>
mkdir undossier
python3 -m venv ~/undossier
source undossier/bin/activate
</code>

=== Sous Windows ===
<code powershell>
python -m venv undossier
.\undossier\Scripts\activate
</code>

Comme je suis une feignasse, j'ai fait un script PowerShell pour ne pas me faire chier sous Windows : 

<file powershell venv.ps1>
$path_global = "H:\Dev"
$path_venv = "Python\venv"
$py_activate = "Scripts\activate.ps1"
Set-Location -Path $path_global
powershell -noexit ".\$path_venv\$py_activate ; cd Pelican-test"
</file>

Et je le lance avec un batch (oui) en utilisant Windows Terminal : 
<file batch start.bat>
@ECHO OFF
SET folder="H:\Dev"
wt PowerShell -c %folder%\venv.ps1
</file>

==== Installer Pelican ====

On installe Pelican : 
<code bash>
pip install "pelican[markdown]"
</code>

===== Créer un premier site =====
On créé un dossier et on lance l'assistant de Pelican : 
<code bash>
mkdir monsupersite
cd monsupersite
pelican-quickstart
</code>

On répond aux questions de l'assistant : 
<code>
pelican-quickstart 
Welcome to pelican-quickstart v4.10.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? Erreur503
> Who will be the author of this web site? Yahiko
> What will be the default language of this web site? [en] fr
> Do you want to specify a URL prefix? e.g., https://example.com   (Y/n) Y
> What is your URL prefix? (see above example; no trailing slash) https://blog.erreur503.xyz
> Do you want to enable article pagination? (Y/n) Y
> How many articles per page do you want? [10] 5
> What is your time zone? [Europe/Rome] Europe/Paris
> Do you want to generate a tasks.py/Makefile to automate generation and publishing? (Y/n) Y
> Do you want to upload your website using FTP? (y/N) N
> Do you want to upload your website using SSH? (y/N) y
> What is the hostname of your SSH server? [localhost] 
> What is the port of your SSH server? [22] 
> What is your username on that server? [root] 
> Where do you want to put your web site on that server? [/var/www] 
> 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 /root/pelican
</code>

===== Créer une page =====
Dans ''monsupersite/content'' on créé un fichier ''md''.

<file md article.md>
Title: Mon super article
Date: 2024/11/13 21:43
Category: 3615 Ma vie
Tags: pelican, ma vie, test, osef
Slug: mon-super-article
Authors: Lapinours

# Titre 1
## Titre 2
Wow, un **super** article sur `Pelican`.

Tellement _beau_ et **_frais_**.
</file>
===== Tester =====

Pour tester rapidement le site il est possible de lancer le serveur web intégré : 
<code bash>
pelican -r -l
</code>

Le site sera accessible sur http://127.0.0.1:8000.

===== Publier =====
<code bash>
pelican /chemin/monsupersite/content -s /chemin/monsupersite/pelicanconf.py
</code>

Pour le développement du site, il est possible d'activer des chemins relatifs dans ''pelicanconfig.py''
<file python pelicanconfig.py>
# Uncomment following line if you want document-relative URLs when developing
RELATIVE_URLS = True
</file>

La commande ''make html'' permet aussi d'exporter le site en HTML en utilisant ''pelicanconfig.py''.

''make publish'' va publier le site selon le fichier de conf ''make publish''

===== Les thèmes =====

Les thèmes Pelican utilisent [[https://jinja.palletsprojects.com/en/stable/templates/|le moteur de template Jinja]]. 

Les documentations utiles : 
  * [[https://docs.getpelican.com/en/4.10.1/themes.html|Pelican - Themes]]
  * [[https://jinja.palletsprojects.com/en/stable/templates/|Jinja - Template Designer Documentation]]

On va éditer le fichier de conf du site pour lui indiquer où est le thème : 

<file python pelicanconf.py>
THEME = "../themes/monsupertheme"
</file>

L'aborescence d'un thème est la suivante (traduite de la doc de Plecian) : 

<code>
├── static
│   ├── css
│   └── images
└── templates
    ├── archives.html         // Archives
    ├── article.html          // Traite les pages pour chaque article
    ├── author.html           // Traite les pages pour chaque auteur
    ├── authors.html          // Liste de tous les auteurs
    ├── categories.html       // Liste de toutes les catégorie
    ├── category.html         // Traite les pages pour chaque catégories
    ├── index.html            // L'index qui liste tous les articles
    ├── page.html             // Traite les pages pour chaque page
    ├── period_archives.html  // Affiche les archives
    ├── tag.html              // Traite les pages pour chaque tag
    └── tags.html             // Liste tous les tags. Peut être un nuage de tags.
</code>