website-pelican/README.md
2020-10-20 20:58:49 +02:00

153 lines
4.4 KiB
Markdown

# 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)