Il workflow¶

Il ciclo di lavoro¶

Una volta configurata l'infrastruttura (operazione una tantum descritta nel capitolo successivo), il ciclo di lavoro quotidiano è lineare:

Scrivi o modifica un file Markdown
Salva nel repository GitHub
Attendi 2-3 minuti per il build automatico
Verifica il risultato sul sito pubblicato

Non serve compilare manualmente, non serve caricare file via FTP, non serve accedere a pannelli di controllo. Il processo di pubblicazione è completamente automatizzato.

Scrivere in Markdown¶

Markdown è un formato di testo con convenzioni semplici per la formattazione:

# Titolo principale
## Sottotitolo
### Sezione

Testo normale con **grassetto** e *corsivo*.

- Elenco puntato
- Secondo elemento

1. Elenco numerato
2. Secondo elemento

[Link a una pagina](https://esempio.it)

![Descrizione immagine](percorso/immagine.png)

Il vantaggio di Markdown è la leggibilità: anche senza rendering, il testo sorgente è comprensibile. E la portabilità: lo stesso file può essere convertito in HTML, PDF, DOCX, o altri formati.

Material for MkDocs estende Markdown con funzionalità aggiuntive, come i callout:

!!! note "Nota"
    Questo è un box di nota.

!!! warning "Attenzione"
    Questo è un avviso.

!!! tip "Suggerimento"
    Questo è un suggerimento.

Modificare contenuti esistenti¶

Per modifiche semplici, l'interfaccia web di GitHub è sufficiente:

Naviga al file nel repository
Clicca l'icona matita (Edit)
Modifica il contenuto
Clicca "Commit changes"

Il workflow automatico parte immediatamente. In 2-3 minuti la modifica è online.

Per modifiche più sostanziali, o per lavorare offline, si può clonare il repository in locale, modificare con qualsiasi editor di testo, e fare push delle modifiche.

Aggiungere nuove pagine¶

Aggiungere una pagina richiede due passaggi:

Creare il file .md nella cartella appropriata
Aggiungere il riferimento in mkdocs.yml nella sezione nav:

La struttura di navigazione è esplicita: se una pagina non è in nav:, non appare nel menu (ma resta accessibile via URL diretto).

Anteprima locale¶

Per vedere il risultato prima di pubblicare, MkDocs include un server di sviluppo:

mkdocs serve

Il sito è visibile su http://localhost:8000 con aggiornamento automatico a ogni modifica salvata. Richiede MkDocs installato localmente (pip install mkdocs-material).

Questo passaggio è opzionale: si può anche pubblicare direttamente e verificare sul sito live. Per piccole modifiche è spesso più veloce.

Scaricare il PDF¶

Ogni manuale è disponibile anche in versione PDF per la consultazione offline o la stampa. Il link per il download si trova nella home page del sito e nella pagina di introduzione di ogni manuale.

Il PDF viene rigenerato automaticamente a ogni aggiornamento del sito, quindi è sempre allineato con la versione web. Include copertina, indice navigabile e numerazione dei capitoli.

Quando usare il PDF

Il canale principale resta il web, che garantisce contenuti sempre aggiornati. Il PDF è utile per situazioni specifiche: consultazione senza connessione, stampa per corsi in aula, archiviazione di una versione datata.

Generazione manuale con Pandoc¶

Per esigenze specifiche (formattazione personalizzata, layout particolare) è possibile generare PDF manualmente usando Pandoc:

pandoc docs/manuale/*.md -o manuale.pdf \
  --template eisvogel \
  --pdf-engine=xelatex \
  --toc --number-sections \
  -V lang=it

Il template Eisvogel produce PDF di qualità professionale. Richiede Pandoc e LaTeX installati localmente.