PELICAN WEBSITE HOWTO

TL;DR:

Per avere un setup di test locale:

virtualenv -p /usr/bin/python3 env
source env/bin/activate

pip install pelican
pip install icalendar
pip install markdown

Ogni volta che si decide di lanciare il sito da un terminale diverso occorrerà fare soltanto:

source env/bin/activate

Per provare il sito sul proprio pc:

make devserver

e poi aprire nel proprio browser 127.0.0.1:8000

CONFIGURAZIONE GENERALE

pelicanconf.py:

in questo file si definiscono un tot di variabili, si rimanda alla documentazione di pelican per una descrizione piu’ approfondita, che definiscono come pelican gestisce i contenuti. Due di queste variabili sono fondamentali per definire l’output del sito e sono:

• THEME - che definisce il tema usato. Al momento usiamo minimunit, un tema derivato dal tema “minimo” di dan (https://git.abbiamoundominio.org/dan/minimo)

• MENUITEM - che definisce il “menu” che compare nella parte superiore di ogni pagina.

  • HOME (index)
  • BLOG (lista degli articoli con anteprima (articles.html), volendo ci sarebbe anche la pagina archives.html che contiene la lista degli articoli ma senza anteprima.
  • CATEGORIE (lista delle categorie degli articoli, cliccabile)
  • TAG (lista dei tag degli articoli, cliccabile)
  • CONTATTI (pagina che riporta i contatti)
  • RSS (link al feed rss (atom))

• PLUGINS - che definisce quali plugins sono attivi

publishconf.py

questo file definisce solo il SITEURL in produzione e l’indirizzo dei feed rss e atom creati.

Makefile

e’ il makefile standard con le istruzioni per SSH per caricare il sito e un nuovo comando “production” per copiare il sito al suo posto (ma funziona solo se viene lanciato da zaphoda)

MODIFICARE IL SITO/AGGIUNGERE CONTENUTI

per lavorare sul sito clonare il repository:

git clone ssh://git@git.abbiamoundominio.org:10022/unit/website-pelican.git

i contenuti stanno nella cartella “content”, vengono scritti in markdown e sono di due tipi:

• pagine statiche (nella sottocartella “pages”)
• articoli tipo blog (nella sottocartella “blog”)

una volta elaborati da pelican vengono salvati nella cartella “output” che e’ quella che conterrà i files .html del sito vero e proprio

le pagine e gli articoli si scrivono in formato markdown e devono contenere dei metadati:

per le pagine statiche questi sono obbligatori:

• Title: titolo (il titolo che poi compare a video nella pagina finale html)
• Slug: nome_pagina (il nome con cui la pagina sara’ salvata nella cartella output)

ci sono altri metadati facoltativi, ad es. 404.md usa: Save_as: 404.html che fa override della direttiva PAGE_SAVE_AS e permette di salvare la pagina come 404.html nella root invece che nella sottocartella 404

per gli articoli invece i metadati sono ad es.:

• Title: Comunicato Unit hacklab su annuncio sgombero Macao
• Author: Unit
• Category: comunicato
• Date: 2018-09-26
• Tags: sgombero

e’ possibile anche inserire dei parametri aggiuntivi per impostare un calendario ics, utile per gli eventi:

• Event-start: 2019-04-25 10:30
• Event-duration: 2h
• Event-location: somewhere
• Event-recurring: weekly until 2019-06-20

ci sono maggiori dettagli in plugins/events-readme.md

IMMAGINI NEL SITO

le immagini nel sito/pagine/articoli devono essere salvate in due cartelle:

• media (che contiene i materiali delle pagine, pdf, immagini etc.)
• images (che contiene le immagini della struttura del sito, al momento solo il logo))

FEED RSS

gli articoli finiscono nel feed rss, le pagine no, quindi se si crea una pagina e’ bene fare anche un articolo che la “presenti”.

MANDARE LE MODIFICHE IN PRODUZIONE

lanciando make pelican puo’ rigenerare i contenuti, prende i files markdown e genera gli html salvandoli nella cartella output.

Vedere il Makefile per tutte le opzioni, cmq le due piu’ importanti sono:

make devserver

rigenera i contenuti e fa partire un webserver su localhost:8000 dove si possono vedere le modifiche

make production (funziona solo avete clonato il repository su zaphoda)

copia la cartella output in /var/www/unit.abbiamoundominio.org dove viene servita da nginx.

**nota: ** quando si rigenera il sito le pagine e gli articoli sono salvati: nella cartella output/nome_pagina/index.html (come definito nella variabile PAGE_SAVE_AS in pelicanconf.py) e nella cartella output/blog/data-titolo.html (come definito nella variabile ARTICLE_SAVE_AS in pelicanconf.py)