Browse Source

updated documentation

putro 4 weeks 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 @@
1 1
 # PELICAN WEBSITE HOWTO
2 2
 
3
-## pelicanconf.py:
3
+## CONFIGURAZIONE GENERALE
4 4
 
5
-in questo file si definiscono un tot di cose, tra cui:
5
+### pelicanconf.py:
6 6
 
7
- i contenuti stanno nella cartella "content", vengono scritti in markdown e sono di due tipi:
7
+in questo file si definiscono un tot di variabili, si rimanda alla documentazione di pelican
8
+per una descrizione piu' approfondita, che definiscono come pelican gestisce i contenuti.
9
+Due di queste variabili sono fondamentali per definire l'output del sito e sono:
8 10
 
9
- - pagine statiche (nella sottocartella "pages")
10
- - articoli tipo blog (nella sottocartella "blog")
11
- 
12
- una volta elaborati sono salvati nella cartella "output" che e' quella
11
+- THEME - che definisce il tema usato.
12
+  Al momento usiamo minimunit, un tema derivato dal tema "minimo" di dan (https://git.abbiamoundominio.org/dan/minimo)
13
+
14
+- MENUITEM - che definisce il "menu" che compare nella parte superiore di ogni pagina.
15
+
16
+	- HOME (index)
17
+	- 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.
18
+	- CATEGORIE (lista delle categorie degli articoli, cliccabile)
19
+	- TAG (lista dei tag degli articoli, cliccabile)
20
+	- CONTATTI  (pagina che riporta i contatti)
21
+	- RSS (link al feed rss (atom))
22
+
23
+
24
+- PLUGINS - che definisce quali plugins sono attivi
25
+
26
+
27
+### publishconf.py
28
+
29
+questo file definisce solo il SITEURL in produzione e l'indirizzo dei feed rss e atom creati.
30
+
31
+
32
+### Makefile
33
+
34
+e' il makefile standard con le istruzioni per SSH per caricare il sito
35
+e un nuovo comando "production" per copiare il sito al suo posto
36
+(ma funziona solo se viene lanciato da zaphoda)
37
+
38
+
39
+## MODIFICARE IL SITO/AGGIUNGERE CONTENUTI
40
+
41
+per lavorare sul sito clonare il repository:
42
+
43
+> git clone ssh://git@git.abbiamoundominio.org:10022/unit/website-pelican.git
44
+
45
+i contenuti stanno nella cartella "content", vengono scritti in markdown e sono di due tipi:
46
+
47
+ - **pagine** statiche (nella sottocartella "pages")
48
+ - **articoli** tipo blog (nella sottocartella "blog")
49
+
50
+ una volta elaborati da pelican vengono salvati nella cartella "output" che e' quella
13 51
  che conterrà i files .html del sito vero e proprio
14
- 
15
-in testa ai files .md devono essere definiti dei metadati:
16 52
 
17
-per le pagine statiche: 
53
+le pagine e gli articoli si scrivono in formato markdown e devono contenere dei metadati:
18 54
 
19
-- Title  (il titolo che poi compare a video nella pagina finale html) 
20
-- Slug (il nome con cui la pagina sara' salvata nella cartella output)
55
+per le **pagine** statiche questi sono obbligatori:
21 56
 
22
-ad es. index.md ha un Save_as: index.html che fa override della direttiva PAGE_SAVE_AS
23
-e permette di salvare la pagina come index.html nella root invece che nella sottocartella index   
57
+- Title: titolo     (il titolo che poi compare a video nella pagina finale html)
58
+- Slug: nome_pagina   (il nome con cui la pagina sara' salvata nella cartella output)
24 59
 
25
-per gli articoli ad es.:
60
+
61
+ci sono altri metadati facoltativi, ad es. 404.md usa:
62
+Save_as: 404.html
63
+che fa override della direttiva PAGE_SAVE_AS e permette di salvare la pagina come 404.html nella root invece che nella sottocartella 404
64
+
65
+
66
+per gli **articoli** invece i metadati sono ad es.:
26 67
 
27 68
 - Title: Comunicato Unit hacklab su annuncio sgombero Macao
28
-- Author: Unit 
69
+- Author: Unit
29 70
 - Category: comunicato
30 71
 - Date: 2018-09-26
31 72
 - Tags: sgombero
32 73
 
33
-nella cartella output le pagine sono salvate nella sottocartella nome_pagina/index.html
34
-(direttiva PAGE_SAVE_AS)
35
-si possono fare eccezioni a questo, ad esempio la pagina index non puo' finire in index/index.html,
36
-quindi si definisce il metadato Save_as che fa override di PAGE_SAVE_AS e definisce come salvare la pagina,
37
-in questo caso specificando index.html finisce nella root (stessa cosa si fa per la pagina 404.md)
74
+e' possibile anche inserire dei parametri aggiuntivi per impostare un calendario ics, utile per gli eventi:
75
+
76
+- Event-start: 2019-04-25 10:30
77
+- Event-duration: 2h
78
+- Event-location: somewhere
79
+- Event-recurring: weekly until 2019-06-20
80
+
81
+ci sono maggiori dettagli in plugins/events-readme.md
82
+
83
+#### IMMAGINI NEL SITO
84
+
85
+le immagini nel sito/pagine/articoli devono essere salvate in due cartelle:
86
+
87
+- media (che contiene i materiali delle pagine, pdf, immagini etc.)
88
+- images (che contiene le immagini della struttura del sito, al momento solo il logo))
89
+
90
+
38 91
 
39
-gli articoli invece vengono salvati nella cartella blog (direttiva ARTICLE_SAVE_AS)
92
+#### FEED RSS
40 93
 
41
-gli articoli finiscono nel feed rss, le pagine no, quindi se si crea una pagina 
94
+gli articoli finiscono nel feed rss, le pagine no, quindi se si crea una pagina
42 95
 e' bene fare anche un articolo che la "presenti".
43 96
 
44 97
 
45
-il tema usato e' "minimo" di dan  ed e' definito come submodule di git
98
+## MANDARE LE MODIFICHE IN PRODUZIONE
46 99
 
47
-quindi ora per clonare il repository:
100
+lanciando make pelican puo' rigenerare i contenuti, prende i files markdown e genera gli html salvandoli
101
+nella cartella output.
48 102
 
49
-> git clone --recursive    (--recursive per fare anche il clone dei submodules)
50 103
 
51
-> git submodule update --init
104
+Vedere il Makefile per tutte le opzioni, cmq le due piu' importanti sono:
52 105
 
53
-per lavorare sul repository, fare pull e aggiornare anche il submodulo:
106
+> make devserver
54 107
 
55
-> git pull --recurse-submodules
108
+rigenera i contenuti e fa partire un webserver su localhost:8000 dove si possono vedere le modifiche
56 109
 
57
-> git submodule update --remote
110
+> make production  (funziona solo avete clonato il repository su zaphoda)
58 111
 
59
-se il submodule contiene degli aggiornamenti, bisogna committarli nel repository del sito:
112
+copia la cartella output in /var/www/unit.abbiamoundominio.org dove viene servita da nginx.
113
+
114
+
115
+**nota: **
116
+quando si rigenera il sito le pagine e gli articoli sono salvati:
117
+nella cartella output/nome_pagina/index.html
118
+(come definito nella variabile PAGE_SAVE_AS in pelicanconf.py)
119
+e nella cartella output/blog/data-titolo.html
120
+(come definito nella variabile ARTICLE_SAVE_AS in pelicanconf.py)
60 121
 
61
-> git add theme/minimo
62 122
 
63
-> git commit -m "aggiornato tema"
64 123
 
65
-> git push
66 124
 
67 125
 
68
-in cima alla pagina c'e' un piccolo menu con poche voci:
69 126
 
70
-- HOME (index)
71
-- 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.
72
-- CATEGORIE (lista delle categorie degli articoli, cliccabile)
73
-- TAG (lista dei tag degli articoli, cliccabile)
74
-- CONTATTI  (pagina che riporta i contatti)
75
-- RSS (link al feed rss (atom)) 
76
- 
77
-ci sono due cartelle statiche:
78 127
 
79
-- media (che contiene i materiali delle pagine, pdf, immagini etc.)
80
-- images (che contiene le immagini della struttura del sito, al momento solo il logo))
81 128
 
82 129
 
83 130
 
84
-## publishconf.py
85 131
 
86
-questo file definisce solo il SITEURL in produzione e l'indirizzo dei feed rss e atom creati
87
-(quando sostituiremo il sito perderemo tutti i feed precedenti, a meno di creare degli articoli nel blog,
88
-pero' poi mi sa che chi ha sottoscritto il feed li ricevera' di nuovo.... ?
89
-per or
90 132
 
91 133
 
92
-## Makefile
93 134
 
94
-e' il makefile standard con le istruzioni per SSH per caricare il sito
95
-e un nuovo comando "production" per copiare il sito al suo posto 
96
-(ma funziona solo se viene lanciato da zaphoda)
97 135
 
98 136
 

Loading…
Cancel
Save