Setup iniziale¶

Questa sezione descrive la configurazione una tantum dell'infrastruttura. Una volta completata, il sistema funziona in autonomia e il lavoro quotidiano si riduce alla scrittura e modifica dei contenuti.

Prerequisiti¶

Account GitHub: gratuito per repository pubblici. GitHub Pro (4$/mese) per repository privati con GitHub Pages pubbliche, utile se vuoi sviluppare in privato prima di pubblicare.

Un dominio o sottodominio: può essere un dominio dedicato (docs.esempio.it) o un sottodominio di un sito esistente. Serve accesso al pannello DNS per la configurazione.

MkDocs e Material (opzionale per sviluppo locale):

pip install mkdocs-material

Creare il repository¶

Su GitHub, crea un nuovo repository:

Nome: scegli un nome descrittivo (es. docs-miosito)
Visibilità: Private se hai GitHub Pro e vuoi sviluppare in privato, altrimenti Public
Inizializzazione: non selezionare nulla (né README, né .gitignore)

Struttura dei file¶

Il repository deve contenere questa struttura minima:

repository/
├── .github/
│   └── workflows/
│       └── deploy.yml      # Workflow di build e deploy
├── docs/
│   ├── index.md            # Home page
│   └── CNAME               # Dominio custom (una riga col dominio)
└── mkdocs.yml              # Configurazione MkDocs

Il file mkdocs.yml¶

Configurazione base:

site_name: Nome del tuo sito
site_url: https://tuodominio.it/
site_author: Tuo Nome

theme:
  name: material
  language: it
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Passa alla modalità scura
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Passa alla modalità chiara
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.top
    - search.suggest
    - search.highlight

nav:
  - Home: index.md

plugins:
  - search:
      lang: it

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences
  - toc:
      permalink: true

Il file deploy.yml¶

Questo file in .github/workflows/ automatizza build e pubblicazione:

name: Deploy MkDocs to GitHub Pages

on:
  push:
    branches:
      - main

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.x'
      - run: pip install mkdocs-material
      - run: mkdocs build
      - uses: actions/configure-pages@v4
      - uses: actions/upload-pages-artifact@v3
        with:
          path: site/

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - uses: actions/deploy-pages@v4

Il file CNAME¶

Un file di testo con una sola riga: il tuo dominio.

docs.tuodominio.it

La home page¶

Il file docs/index.md sarà la prima pagina del sito. Può essere minimale inizialmente e arricchito in seguito.

Caricare i file su GitHub¶

Se usi l'interfaccia web:

Nel repository, clicca "Add file" → "Create new file"
Per creare cartelle, scrivi il percorso completo (es. .github/workflows/deploy.yml)
Incolla il contenuto e salva con "Commit changes"

File nascosti

I file che iniziano con . (come .github) sono nascosti nei sistemi operativi. Il drag-and-drop dal file manager potrebbe non caricarli. Usa "Create new file" per crearli direttamente su GitHub.

Configurare GitHub Pages¶

Vai in Settings del repository
Sezione Pages nel menu laterale
Source: seleziona "GitHub Actions"
Custom domain: inserisci il tuo dominio (es. docs.tuodominio.it)

Configurare i permessi del workflow¶

Se il primo deploy fallisce con errore sui permessi:

Settings → Actions → General
Sezione Workflow permissions
Seleziona Read and write permissions
Salva

Configurare il DNS¶

Nel pannello di gestione del tuo dominio, aggiungi un record DNS:

Tipo	Nome	Valore
CNAME	`docs` (o `@` per dominio principale)	`tuousername.github.io`

Sostituisci tuousername con il tuo username GitHub e docs con il sottodominio scelto.

La propagazione DNS può richiedere da pochi minuti a 24 ore. GitHub Pages verificherà automaticamente la configurazione.

Verifica¶

Dopo la propagazione DNS e il completamento del workflow:

Vai nella tab Actions del repository
Verifica che il workflow sia completato (spunta verde)
Visita il tuo dominio nel browser

Se vedi la home page, il setup è completato. Ogni push sul branch main aggiornerà automaticamente il sito.