updated documentation
This commit is contained in:
parent
66579e2375
commit
78b821baaa
170
LEGGIMI.md
170
LEGGIMI.md
|
|
@ -1,98 +1,136 @@
|
||||||
# PELICAN WEBSITE HOWTO
|
# 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")
|
- THEME - che definisce il tema usato.
|
||||||
- articoli tipo blog (nella sottocartella "blog")
|
Al momento usiamo minimunit, un tema derivato dal tema "minimo" di dan (https://git.abbiamoundominio.org/dan/minimo)
|
||||||
|
|
||||||
una volta elaborati sono salvati nella cartella "output" che e' quella
|
- 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
|
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)
|
per le **pagine** statiche questi sono obbligatori:
|
||||||
- Slug (il nome con cui la pagina sara' salvata nella cartella output)
|
|
||||||
|
|
||||||
ad es. index.md ha un Save_as: index.html che fa override della direttiva PAGE_SAVE_AS
|
- Title: titolo (il titolo che poi compare a video nella pagina finale html)
|
||||||
e permette di salvare la pagina come index.html nella root invece che nella sottocartella index
|
- 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
|
- Title: Comunicato Unit hacklab su annuncio sgombero Macao
|
||||||
- Author: Unit
|
- Author: Unit
|
||||||
- Category: comunicato
|
- Category: comunicato
|
||||||
- Date: 2018-09-26
|
- Date: 2018-09-26
|
||||||
- Tags: sgombero
|
- Tags: sgombero
|
||||||
|
|
||||||
nella cartella output le pagine sono salvate nella sottocartella nome_pagina/index.html
|
e' possibile anche inserire dei parametri aggiuntivi per impostare un calendario ics, utile per gli eventi:
|
||||||
(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)
|
|
||||||
|
|
||||||
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
|
ci sono maggiori dettagli in plugins/events-readme.md
|
||||||
e' bene fare anche un articolo che la "presenti".
|
|
||||||
|
|
||||||
|
#### IMMAGINI NEL SITO
|
||||||
|
|
||||||
il tema usato e' "minimo" di dan ed e' definito come submodule di git
|
le immagini nel sito/pagine/articoli devono essere salvate in due cartelle:
|
||||||
|
|
||||||
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:
|
|
||||||
|
|
||||||
- media (che contiene i materiali delle pagine, pdf, immagini etc.)
|
- media (che contiene i materiali delle pagine, pdf, immagini etc.)
|
||||||
- images (che contiene le immagini della struttura del sito, al momento solo il logo))
|
- 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)
|
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue
Block a user