website-pelican/README.md

# 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](http://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)