Guida introduttiva ad Astro-Theme-Aither

Questa guida ti accompagna da zero fino a un blog multilingue pubblicato. Puoi leggerla dall’inizio alla fine oppure saltare direttamente alla sezione che ti serve.

Prerequisiti

• Node.js 22 LTS o successivo
• pnpm 10 o successivo
• Un account GitHub
• Un account Cloudflare per il deploy

Installazione

git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
cd YOUR_REPO
corepack enable
pnpm install
pnpm validate
pnpm dev

Poi apri http://localhost:4321.

Struttura del progetto

src/
├── components/        # Componenti Astro e React
├── config/site.ts     # Nome sito, navigazione, footer e link social
├── content/posts/     # Post organizzati per locale
├── i18n/              # Traduzioni UI
├── layouts/           # Layout
├── lib/               # Utility
├── pages/             # Pagine e route
└── styles/global.css  # Token tema in Tailwind v4

Configurazione

Site Config

src/config/site.ts è la fonte unica di configurazione:

1
export const siteConfig = {
2
  name: 'Il nome del tuo blog',
3
  title: 'Il tuo sottotitolo',
4
  description: 'La tua descrizione SEO',
5
  author: {
6
    name: 'Il tuo nome',
7
    avatar: '',
8
  },
9
};

Variabili d’ambiente

cp .env.example .env

Lascia vuota una variabile per disattivare il relativo servizio.

URL del sito

Configura l’URL finale in astro.config.mjs:

1
import { defineConfig } from 'astro/config';
2
import aither from '@aither/astro';
3

4
export default defineConfig({
5
  site: 'https://your-domain.pages.dev',
6
  integrations: [aither()],
7
});

Scrivere post

Crea un file .mdx in src/content/posts/en/:

1
---
2
title: Il mio primo post
3
date: "2026-03-14T16:00:00+08:00"
4
category: General
5
description: Un breve riepilogo per SEO e anteprime social.
6
tags: [Topic, Another]
7
pinned: false
8
---
9

10
Il contenuto inizia qui.

Riferimento frontmatter

Componenti MDX

Puoi importare componenti direttamente nei contenuti:

1
import MyChart from '@/components/MyChart'
2

3
<MyChart data={[10, 20, 30]} />

Internazionalizzazione

Il tema supporta 11 lingue. Per aggiungere una traduzione, crea lo stesso file nella cartella del locale desiderato:

src/content/posts/en/my-post.mdx
src/content/posts/it/my-post.mdx
src/content/posts/zh-hans/my-post.mdx

I testi dell’interfaccia si trovano in src/i18n/messages/.

Sezioni di contenuto personalizzate

Puoi aggiungere raccolte come traduzioni, note o tutorial registrandole in src/content.config.ts e src/config/site.ts. Le pagine elenco e dettaglio verranno generate automaticamente.

Theming

Il sistema ha due livelli:

• modalità colore: light, dark, system
• stile tema: default o uno stile integrato come evolution

1
ui: {
2
  defaultMode: 'system',
3
  defaultStyle: 'default',
4
  showMoreThemesMenu: true,
5
},

I colori vivono in src/styles/global.css. Il tema usa di default uno stack sans-serif di sistema e uno stack monospace per il codice.

SEO e AI

Ogni pagina espone già questi output:

• /sitemap-index.xml
• /rss.xml
• /robots.txt
• /llms.txt
• /llms-full.txt
• /posts/slug.md
• JSON-LD e Open Graph

Deploy

Cloudflare Pages

Buona pratica: crea prima il progetto Pages. Il flusso usa il nome del repository per default, oppure CLOUDFLARE_PAGES_PROJECT_NAME se vuoi sovrascriverlo.

Aggiungi questi secret in GitHub:

• CLOUDFLARE_API_TOKEN
• CLOUDFLARE_ACCOUNT_ID

Poi esegui pnpm validate e fai push su main.

Comandi utili

Schema di versione

I tag di release pubblici seguono nomi in stile CalVer, ad esempio v2026.04.08.