Vai al contenuto

Step 12 — Documentazione living su Pages¶

Obiettivo: una documentazione che vive con il codice.

Stack documentazione¶

MkDocs Material — tema moderno, dark/light, search, mermaid, admonitions, grid cards.
Hostato su GitHub Pages — deploy automatico via Actions.
Edit on GitHub — ogni pagina ha il link "modifica" che apre la sorgente in docs/.

`mkdocs.yml` rilevanti¶

mkdocs.yml (estratto)

site_name: Spring Boot From Scratch
site_url: https://fedcal.github.io/Spring-Boot-From-Scratch/
repo_url: https://github.com/fedcal/Spring-Boot-From-Scratch
edit_uri: edit/main/docs/

copyright: >
  Copyright &copy; 2026 Federico Calò —
  <a href="https://federicocalo.dev">federicocalo.dev</a>

theme:
  name: material
  language: it
  features:
    - navigation.tabs
    - search.suggest
    - content.code.copy
  palette:
    - scheme: default
      primary: green
    - scheme: slate
      primary: green

Cosa includere¶

Tipo di pagina	Esempio	Frequenza aggiornamento
Reference	API endpoints, configurazione	con ogni change
How-to	"Come avviare in prod", troubleshooting	con feedback utenti
Concetti	Architettura, ADR	con decisioni nuove
Tutorial	Guida step-by-step	con feature didattiche

Workflow: docs change → live in 2 minuti¶

sequenceDiagram
    actor Dev
    participant Repo as GitHub repo
    participant CI as GitHub Actions
    participant Pages as GitHub Pages

    Dev->>Repo: push (docs/*.md)
    Repo->>CI: trigger docs.yml
    CI->>CI: mkdocs build --strict
    CI->>Pages: deploy artifact
    Pages-->>Dev: live URL

mkdocs build --strict fallisce su link rotti — funge da CI per la documentazione.

Esercizi¶

Aggiungi una pagina "FAQ" con Q&A formattati con admonitions.
Configura un plugin di analytics privacy-friendly (es. Plausible).
Pubblica su un dominio custom (docs.tuodominio.dev) con CNAME.

Riferimenti nel codice¶