Browse Source

updated documentation

master
putro 1 year ago
parent
commit
78b821baaa
1 changed files with 92 additions and 54 deletions
  1. +92
    -54
      LEGGIMI.md

+ 92
- 54
LEGGIMI.md View File

@@ -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:

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



gli articoli invece vengono salvati nella cartella blog (direttiva ARTICLE_SAVE_AS)
#### FEED RSS

gli articoli finiscono nel feed rss, le pagine no, quindi se si crea una pagina
gli articoli finiscono nel feed rss, le pagine no, quindi se si crea una pagina
e' bene fare anche un articolo che la "presenti".


il tema usato e' "minimo" di dan ed e' definito come submodule di git
## MANDARE LE MODIFICHE IN PRODUZIONE

quindi ora per clonare il repository:
lanciando make pelican puo' rigenerare i contenuti, prende i files markdown e genera gli html salvandoli
nella cartella output.

> git clone --recursive (--recursive per fare anche il clone dei submodules)

> git submodule update --init
Vedere il Makefile per tutte le opzioni, cmq le due piu' importanti sono:

per lavorare sul repository, fare pull e aggiornare anche il submodulo:
> make devserver

> git pull --recurse-submodules
rigenera i contenuti e fa partire un webserver su localhost:8000 dove si possono vedere le modifiche

> git submodule update --remote
> make production (funziona solo avete clonato il repository su zaphoda)

se il submodule contiene degli aggiornamenti, bisogna committarli nel repository del sito:
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)

> 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.)
- images (che contiene le immagini della struttura del sito, al momento solo il logo))



## publishconf.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…
Cancel
Save