updated documentation

proposta-home
putro 2019-04-26 13:17:47 +02:00
rodzic 66579e2375
commit 78b821baaa
1 zmienionych plików z 104 dodań i 66 usunięć

Wyświetl plik

@ -1,98 +1,136 @@
# PELICAN WEBSITE HOWTO
## pelicanconf.py:
## CONFIGURAZIONE GENERALE
in questo file si definiscono un tot di cose, tra cui:
### pelicanconf.py:
i contenuti stanno nella cartella "content", vengono scritti in markdown e sono di due tipi:
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:
- pagine statiche (nella sottocartella "pages")
- articoli tipo blog (nella sottocartella "blog")
una volta elaborati sono salvati nella cartella "output" che e' quella
- 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
in testa ai files .md devono essere definiti dei metadati:
per le pagine statiche:
le pagine e gli articoli si scrivono in formato markdown e devono contenere dei metadati:
- Title (il titolo che poi compare a video nella pagina finale html)
- Slug (il nome con cui la pagina sara' salvata nella cartella output)
per le **pagine** statiche questi sono obbligatori:
ad es. index.md ha un Save_as: index.html che fa override della direttiva PAGE_SAVE_AS
e permette di salvare la pagina come index.html nella root invece che nella sottocartella index
- 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)
per gli articoli ad es.:
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
- Author: Unit
- Category: comunicato
- Date: 2018-09-26
- Tags: sgombero
nella cartella output le pagine sono salvate nella sottocartella nome_pagina/index.html
(direttiva PAGE_SAVE_AS)
si possono fare eccezioni a questo, ad esempio la pagina index non puo' finire in index/index.html,
quindi si definisce il metadato Save_as che fa override di PAGE_SAVE_AS e definisce come salvare la pagina,
in questo caso specificando index.html finisce nella root (stessa cosa si fa per la pagina 404.md)
e' possibile anche inserire dei parametri aggiuntivi per impostare un calendario ics, utile per gli eventi:
gli articoli invece vengono salvati nella cartella blog (direttiva ARTICLE_SAVE_AS)
- Event-start: 2019-04-25 10:30
- Event-duration: 2h
- Event-location: somewhere
- Event-recurring: weekly until 2019-06-20
gli articoli finiscono nel feed rss, le pagine no, quindi se si crea una pagina
e' bene fare anche un articolo che la "presenti".
ci sono maggiori dettagli in plugins/events-readme.md
#### IMMAGINI NEL SITO
il tema usato e' "minimo" di dan ed e' definito come submodule di git
quindi ora per clonare il repository:
> git clone --recursive (--recursive per fare anche il clone dei submodules)
> git submodule update --init
per lavorare sul repository, fare pull e aggiornare anche il submodulo:
> git pull --recurse-submodules
> git submodule update --remote
se il submodule contiene degli aggiornamenti, bisogna committarli nel repository del sito:
> git add theme/minimo
> git commit -m "aggiornato tema"
> git push
in cima alla pagina c'e' un piccolo menu con poche voci:
- 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))
ci sono due cartelle statiche:
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))
## publishconf.py
#### 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)
questo file definisce solo il SITEURL in produzione e l'indirizzo dei feed rss e atom creati
(quando sostituiremo il sito perderemo tutti i feed precedenti, a meno di creare degli articoli nel blog,
pero' poi mi sa che chi ha sottoscritto il feed li ricevera' di nuovo.... ?
per or
## 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)