Creare con l’IA

Gli editor con IA e gli agenti di programmazione spesso tirano a indovinare su sitelo — ricorrono a schemi di React, Next o Astro che qui non valgono. Questa guida mostra come indirizzarli alla documentazione aggiornata di sitelo e mantenere il codice generato in linea con il modello.

llms.txt

sitelo pubblica un riassunto del framework leggibile dalle macchine su sitelo.dev/llms.txt. Molti agenti sanno scaricare un URL; chiedi al tuo di leggere quel file (e la documentazione per umani) prima di scrivere codice sitelo.

• https://sitelo.dev/llms.txt — API e convenzioni in forma compatta
• https://sitelo.dev/docs — guide complete
• README su GitHub — modello mentale e panoramica delle funzionalità
• https://ht.js.org — documentazione di javascript-to-html (consigliata per scrivere HTML in JS)

A differenza di un server MCP per la documentazione, llms.txt non richiede installazioni — incolla l’URL nella chat, aggiungilo alle regole di progetto, oppure lascia che sia l’agente a scaricarlo.

Regole di progetto

Se il tuo strumento supporta istruzioni persistenti (AGENTS.md, regole di Cursor, istruzioni di Copilot, …), aggiungi una breve regola su sitelo così ogni sessione parte con il modello mentale giusto. L’esempio di base contiene un AGENTS.md che puoi copiare:

# sitelo

This project uses [sitelo](https://sitelo.dev) — a Vite-powered static site generator.

## Rules

- Pages are modules under `src/` with extensions like `.ht.js` / `.ht.ts` / `.ht.jsx` that **export a default function (or string) returning HTML**.
- Do **not** introduce React, Next.js, Astro, or a component/hydration framework unless the user explicitly asks.
- Routing is file-based: `about.ht.js` → `/about`, `[slug].ht.js` → dynamic (use `generateStaticParams` for `sitelo build`).
- Load data with `export async function data(ctx)`. Use `fetchWithCache` from `sitelo` for cached HTTP. Read local JSON with `readJson` / `readJsonCollection` from `sitelo/data`.
- Only JS/CSS referenced from HTML is bundled into `dist/`. Keep server-only code unreferenced so it never ships.
- Config lives in `sitelo.config.js`. Put Vite options under `vite`.
- Commands: `sitelo` (dev), `sitelo build`, `sitelo preview`.
- For current APIs, read https://sitelo.dev/llms.txt and https://sitelo.dev/docs — do not invent APIs from other frameworks.
- Prefer [javascript-to-html](https://ht.js.org) (`ht.js`) for markup: tag functions that return HTML strings. Docs: https://ht.js.org

Cursor

Crea .cursor/rules/sitelo.mdc nel tuo progetto (oppure incolla lo stesso testo nell’interfaccia delle regole di progetto di Cursor):

---
description: sitelo static site conventions
alwaysApply: true
---

# sitelo

Pages are `.ht.js` (etc.) modules that return HTML strings — not React/Next/Astro components.
Prefer javascript-to-html (https://ht.js.org) for markup. Use file-based routing, `data()`, and `sitelo build`.
Prefer https://sitelo.dev/llms.txt for sitelo APIs.

Consigli per lavorare su sitelo con l’IA

• Parti da un modello — chiedi all’agente di generare l’impalcatura da examples/basic o examples/wordpress invece di inventarsi un framework.
• Per il markup preferisci javascript-to-html (ht.js): funzioni-tag che restituiscono stringhe HTML, senza motori di template né React. Indirizza gli agenti a ht.js.org così non si inventano alberi di componenti JSX.
• Le pagine sono funzioni che restituiscono HTML — export default () => `<html>…</html>` oppure composte con javascript-to-html. JSX va bene finché compila in stringhe; un runtime React non serve.
• Usa la CLI di sitelo — sitelo / sitelo build — non vite direttamente, a meno che tu non sappia di aver bisogno di una configurazione Vite personalizzata.
• Verifica le API rispetto a llms.txt — in particolare generateStaticParams, fetchWithCache e le island server.
• Zero JS per impostazione predefinita — collega uno <script> solo quando la pagina ha bisogno di codice client; i moduli non referenziati restano solo lato server.
• Rivedi ed esegui — dopo che l’agente ha modificato le pagine fai sempre sitelo build (o avvia il server di sviluppo); tratta il markup generato come una bozza.

Primi passi · Esempio di base · llms.txt