updated documentation
This commit is contained in:
parent
66579e2375
commit
78b821baaa
170
LEGGIMI.md
170
LEGGIMI.md
|
|
@ -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)
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user