diff --git a/LEGGIMI.md b/LEGGIMI.md index 654c827..b8611cf 100644 --- a/LEGGIMI.md +++ b/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)