Oltrematica Dev Team Website

Sito web ufficiale del team Oltrematica, costruito con Jekyll e Tailwind CSS.

Caratteristiche

• Design moderno e responsive
• Blog integrato con paginazione
• SEO ottimizzato
• Performance elevate
• Tailwind CSS per styling utility-first
• Componenti riutilizzabili

Prerequisiti

• Ruby 2.7 o superiore
• Node.js 18 o superiore
• Bundler

Installazione

1. Installa le dipendenze Ruby

bundle install

2. Installa le dipendenze Node

npm install

Sviluppo

Avvio del server di sviluppo

# Avvia Jekyll con livereload e Tailwind in watch mode
npm run dev

Il sito sarà disponibile su http://localhost:4000

Solo Jekyll (senza Tailwind watch)

npm run serve

Solo compilazione CSS

npm run watch:css

Build per Produzione

npm run build

Questo comando:

1. Compila e minifica il CSS con Tailwind
2. Genera il sito statico in _site/

Struttura del Progetto

/
├── _config.yml              # Configurazione Jekyll
├── _data/                   # Dati strutturati
│   ├── navigation.yml       # Menu di navigazione
│   └── services.yml         # Servizi offerti
├── _includes/               # Componenti riutilizzabili
│   ├── components/          # Componenti atomici
│   ├── head.html           # SEO e meta tags
│   ├── header.html         # Header del sito
│   ├── navigation.html     # Menu di navigazione
│   ├── footer.html         # Footer
│   ├── hero-section.html   # Sezione hero
│   ├── services-grid.html  # Griglia servizi
│   └── blog-preview.html   # Anteprima blog
├── _layouts/                # Template di pagina
│   ├── default.html        # Layout base
│   ├── home.html           # Layout homepage
│   ├── post.html           # Layout articolo blog
│   └── blog.html           # Layout lista blog
├── _posts/                  # Articoli del blog
├── assets/                  # Asset statici
│   ├── css/
│   │   └── main.css        # CSS con Tailwind
│   ├── js/
│   └── images/             # Immagini
├── blog/                    # Sezione blog
│   └── index.html          # Pagina lista articoli
├── index-new.html          # Nuova homepage
├── Gemfile                 # Dipendenze Ruby
├── package.json            # Dipendenze Node
└── tailwind.config.js      # Configurazione Tailwind

Creazione di Contenuti

Workflow per Proporre un Nuovo Articolo

Per contribuire con un nuovo articolo al blog, segui questo processo:

1. Crea un branch dedicato

Stacca un nuovo branch dal main seguendo questa convenzione di naming:

git checkout main
git pull origin main
git checkout -b post/nome-del-post

Usa un nome descrittivo e in kebab-case (es. post/ai-nel-workflow, post/refactoring-legacy-code).

2. Scrivi l'articolo

Crea un nuovo file in _posts/ con il formato: YYYY-MM-DD-titolo.md

---
layout: post
title: "Titolo del Post"
date: 2025-01-15
author: "Nome Cognome"
linkedin: "username-linkedin"
tags: [tag1, tag2, tag3]
reading_time: 5
excerpt: "Breve descrizione del post"
image: /assets/images/post-image.jpg
---

Contenuto del post in markdown...

Campi obbligatori:

• layout: deve essere post
• title: titolo dell'articolo
• date: data di pubblicazione (formato YYYY-MM-DD)
• author: nome completo dell'autore
• linkedin: username LinkedIn dell'autore (senza URL, solo lo username)
• excerpt: breve descrizione per anteprima e SEO
• image: URL dell'immagine di copertina

Campi opzionali:

• tags: array di tag per categorizzare il post
• reading_time: tempo di lettura stimato in minuti

3. Segui le linee guida di scrittura

Consulta il file AGENTS.md per le linee guida su tono e stile di scrittura. Questo file contiene indicazioni essenziali per:

• Scrivere con un tono naturale e autentico
• Evitare uno stile troppo meccanico o schematico
• Usare correttamente maiuscole e punteggiatura
• Strutturare l'articolo in modo fluido

Se usi strumenti AI per aiutarti nella scrittura, il file AGENTS.md contiene istruzioni specifiche da fornire agli agent per ottenere un risultato coerente con il nostro stile editoriale.

4. Fai una Pull Request

Una volta completato l'articolo:

git add .
git commit -m "Nuovo post: titolo del post"
git push origin post/nome-del-post

Quindi apri una Pull Request su main tramite GitHub. Nel corpo della PR:

• Descrivi brevemente il contenuto dell'articolo
• Menziona eventuali particolarità o punti da rivedere
• Se applicabile, indica se hai bisogno di feedback specifici

5. Anteprima online con Cloudflare Pages

Quando fai push sul tuo branch, Cloudflare Pages crea automaticamente una preview deployment che ti permette di vedere come apparirà l'articolo online prima del merge.

Per accedere all'anteprima:

1. Vai alla dashboard di Cloudflare
2. Naviga su Compute / Workers & Pages
3. Seleziona il progetto del sito
4. Troverai il link alla preview del tuo branch nella lista dei deployment

Usa questa anteprima per verificare che tutto sia corretto (formattazione, immagini, link, ecc.) prima di richiedere la review.

Il team revisionerà l'articolo e, una volta approvato, verrà fatto il merge su main e pubblicato.

Aggiungere un Servizio

Modifica _data/services.yml:

- title: "Nome Servizio"
  description: "Descrizione del servizio"
  icon: '<path stroke-linecap="round"...></path>'
  features:
    - "Feature 1"
    - "Feature 2"
    - "Feature 3"

Deployment

GitHub Pages

1. Esegui il build: npm run build
2. Commit e push su GitHub
3. Configura GitHub Pages per usare la branch main e la cartella _site/

Netlify

1. Collega il repository
2. Comando build: npm run build
3. Directory publish: _site

Vercel

1. Importa il repository
2. Framework preset: Jekyll
3. Build command: npm run build
4. Output directory: _site

Personalizzazione

Colori

Modifica i colori brand in tailwind.config.js:

colors: {
  'brand-primary': '#1e40af',
  'brand-secondary': '#64748b',
  'brand-accent': '#3b82f6'
}

Configurazione Sito

Modifica _config.yml per cambiare:

• Titolo e descrizione
• URL del sito
• Link social
• Informazioni di contatto

Fonts

I fonts sono caricati da Google Fonts in _includes/head.html. Puoi modificare il font in:

1. _includes/head.html (link Google Fonts)
2. tailwind.config.js (configurazione font family)

Plugin Jekyll Utilizzati

• jekyll-paginate: Paginazione blog
• jekyll-sitemap: Sitemap XML automatica
• jekyll-seo-tag: Meta tags SEO automatici
• jekyll-feed: RSS feed automatico

Cache Busting e Versioning

Il sito implementa un sistema automatico di cache busting per invalidare la cache del browser ad ogni build.

Come Funziona

Tutti i file CSS e JavaScript vengono automaticamente versionati utilizzando il timestamp di build di Jekyll (site.time). Questo garantisce che ad ogni ricompilazione, i browser scarichino le versioni aggiornate degli asset.

File interessati:

• /assets/css/styles.css → styles.css?v=1234567890
• /assets/js/main.js → main.js?v=1234567890
• /assets/js/code-copy.js → code-copy.js?v=1234567890
• Custom CSS/JS per pagina

Implementazione

Il versioning è gestito automaticamente tramite Liquid template in _includes/head.html:

{% assign asset_version = site.time | date: '%s' %}
<link rel="stylesheet" href="{{ '/assets/css/styles.css' | relative_url }}?v={{ asset_version }}">
<script defer src="{{ '/assets/js/main.js' | relative_url }}?v={{ asset_version }}"></script>

Vantaggi

• ✅ Aggiornamenti immediati: Gli utenti vedono sempre l'ultima versione dopo ogni deploy
• ✅ Nessuna configurazione manuale: Il versioning è completamente automatico
• ✅ Cache ottimizzata: I file non modificati mantengono la cache tra i build
• ✅ SEO-friendly: Non impatta negativamente sulle performance o indicizzazione

Nota per il Deployment

Ogni volta che esegui npm run build o bundle exec jekyll build, viene generato un nuovo hash basato sul timestamp, invalidando automaticamente la cache del browser.

Performance

Il sito è ottimizzato per:

• Caricamento veloce (< 1s)
• SEO (100/100 su Lighthouse)
• Accessibilità (WCAG 2.1)
• Best practices
• Cache busting automatico

Browser Support

• Chrome (ultime 2 versioni)
• Firefox (ultime 2 versioni)
• Safari (ultime 2 versioni)
• Edge (ultime 2 versioni)

Licenza

MIT License - vedi LICENSE per dettagli

Contatti

• Email: devteam@oltrematica.it
• Website: https://oltrematica.dev
• GitHub: https://github.com/Oltrematica

---

Realizzato con ❤️ dal team Oltrematica usando Jekyll e Tailwind CSS