Personalizzazione grafica

Questa pagina raccoglie le opzioni disponibili per personalizzare l'aspetto del sito di documentazione. Il sito e' generato con MkDocs Material a partire da file Markdown.

Stato

Le scelte grafiche sono ancora da definire con il team. Questa pagina serve come riferimento per la discussione.

---

1. Colori e schema

Nel file mkdocs.yml, sezione theme.palette:

theme:
  palette:
    scheme: default        # default (chiaro) oppure slate (scuro)
    primary: blue          # colore principale (header, link, sidebar)
    accent: blue           # colore di accento (hover, selezione)

Colori disponibili per primary e accent: red, pink, purple, deep purple, indigo, blue, light blue, cyan, teal, green, light green, lime, yellow, amber, orange, deep orange, brown, grey, blue grey, black, white.

Si puo' anche offrire un toggle chiaro/scuro all'utente:

theme:
  palette:
    - scheme: default
      primary: blue
      toggle:
        icon: material/brightness-7
        name: Passa al tema scuro
    - scheme: slate
      primary: blue
      toggle:
        icon: material/brightness-4
        name: Passa al tema chiaro

---

2. Logo e favicon

theme:
  logo: img/logo.png          # logo nell'header (consigliato: PNG trasparente)
  favicon: img/favicon.png     # icona del browser tab

I file vanno messi in docs/img/. Dimensioni consigliate:

• Logo: altezza ~40px (viene ridimensionato automaticamente)
• Favicon: 32x32 px o 64x64 px

---

3. Font

Di default MkDocs Material usa Roboto (testo) e Roboto Mono (codice). Si puo' cambiare con qualsiasi Google Font:

theme:
  font:
    text: Roboto             # font del testo
    code: Roboto Mono        # font dei blocchi codice

Per disabilitare i Google Fonts e usare i font di sistema:

theme:
  font: false

---

4. CSS personalizzato

Per personalizzazioni piu' fini (spaziature, dimensioni, stile tabelle, colori specifici), si crea un foglio di stile custom:

File: docs/stylesheets/custom.css

Dichiarazione in mkdocs.yml:

extra_css:
  - stylesheets/custom.css

Esempi di personalizzazione CSS

Colore primario personalizzato (colore esatto del brand):

:root {
  --md-primary-fg-color: #1a5276;    /* colore header e link */
  --md-accent-fg-color: #2e86c1;     /* colore hover e selezione */
}

Larghezza massima del contenuto:

.md-grid {
  max-width: 1400px;    /* default: 1220px */
}

Stile tabelle:

/* Righe alternate colorate */
.md-typeset table tbody tr:nth-child(even) {
  background-color: #f5f5f5;
}

Dimensione font:

.md-typeset {
  font-size: 0.85rem;    /* default: 0.8rem */
}

---

5. Template override (avanzato)

Per modificare la struttura HTML (header, footer, layout), si possono sovrascrivere i template del tema:

theme:
  custom_dir: overrides

La cartella overrides/ replica la struttura dei template di Material. Esempi:

• overrides/main.html — layout principale
• overrides/partials/footer.html — footer personalizzato

Utile per aggiungere un banner, un footer aziendale, o script custom.

---

Decisioni da prendere

Elemento	Opzioni	Note
Colori	Palette predefinita vs colori brand esatti (CSS)	Servono i codici colore Eurocoge
Logo	File PNG/SVG del logo aziendale	Da fornire in versione chiara per header
Font	Roboto (default) vs font aziendale	Verificare se il font e' su Google Fonts
Toggle chiaro/scuro	Si' / No	Aggiunge un pulsante nell'header
Footer	Default vs footer con info aziendali	Richiede template override
Larghezza pagina	Default (1220px) vs piu' larga	Dipende dal tipo di contenuti