Crusco Agentic Content per Joomla: requisiti, installazione, configurazione e utilizzo

Requisiti minimi

L'estensione è compatibile con Joomla! 5 e Joomla! 6.
I requisiti minimi sono quelli delle rispettive versioni Joomla che puoi leggere nella documentazione ufficiale.

Installare Crusco Agentic Content

Prendi il pacchetto di installazione dalla sezione download del tuo account e caricalo in Joomla:

Sistema -> Estensioni -> Installa estensioni

Terminata l'installazione, torna in Sistema -> Estensioni e abilita:

1. System - Crusco Agentic Content

Abilitare gli aggiornamenti

Per ricevere gli aggiornamenti:

1. annota il tuo Download ID
2. in Joomla vai in Sistema -> Siti di aggiornamento -> Crusco Agentic Content
3. inserisci il tuo Download ID nel campo Chiave di download.

Attivare le caratteristiche Pro

Se hai installato la versione Free di Crusco Agentic Content e successivamente sei passato a un piano Personal, Professional o Agency, per attivare le caratteristiche Pro:

1. scarica il pacchetto “Pro” del plugin dalla sezione download del tuo account
2. caricalo in Joomla da Sistema -> Estensioni -> Installa estensioni
3. entra in Sistema -> Plugin -> System - Crusco Agentic Content Pro e imposta le nuove caratteristiche che ti interessano.

Accogliere i bot IA con l'Agent Readability

I motori di ricerca basati sull’Intelligenza Artificiale funzionano in modo nativo con il formato Markdown.

Quando un bot IA legge una pagina HTML si trova davanti a codici di layout, menu, sidebar, footer e script. Per estrarre il testo utile è costretto a fare un dispendioso lavoro di parsing che rischia di frammentare le informazioni o compromettere il significato originale del testo.

Fornire al bot una versione Markdown dei tuoi contenuti garantisce una migliore comprensione del testo e, di conseguenza, citazioni e risposte molto più accurate.

Per evitare qualsiasi rischio di SEO cannibalization o duplicazione dei contenuti, Crusco Agentic Content istruisce automaticamente i motori di ricerca tradizionali (come Google) a non indicizzare la versione Markdown delle tue pagine.

Affinché il Markdown sia correttamente servito a ogni crawler IA (il crawler è un tipo di bot dedicato alla scansione), è necessario che il tuo sito Joomla lo esponga attraverso due metodi, diventati lo standard de facto:

• Content Negotiation
• Endpoint .md dedicato (Markdown mirror).

Puoi attivare sia uno che l'altro per dare compatibilità totale a ogni crawler IA. In entrambe le modalità, Crusco Agentic Content servirà il Markdown rispettando gli header di sicurezza HTTP che hai definito per il tuo sito Joomla, come Strict-Transport-Security (HSTS) e Content-Security-Policy (CSP).

Content Negotiation

La Content Negotiation è il meccanismo HTTP che permette di fornire diversi formati di rappresentazione di una risorsa dallo stesso URL. Il server sceglie quale formato inviare in base all'intestazione Accept del client che la richiede.

Gli utenti (tramite browser) richiedono il codice HTML completo di elementi di navigazione, CSS e script. Al contrario, gli agenti LLM necessitano di un testo pulito, privo di elementi di interfaccia e “fronzoli vari” che li distraggano dal valore reale dei contenuti.

Con questa opzione, Crusco Agentic Content attiva la Content Negotiation seguendo le regole definite in RFC 9110: il tuo sito continuerà a mostrare le pagine in formato HTML agli utenti, ma le convertirà automaticamente nel formato Markdown per servirle ai crawler dei motori di ricerca IA che lo richiedono.

Inoltre, per prevenire lo scambio di formati tra utenti e bot causato dalla cache della CDN, il plugin inserisce i corretti parametri nell'intestazione HTTP di ogni risposta “negoziata”.

Endpoint .md dedicato (Markdown mirror)

Mentre la Content Negotiation agisce “dietro le quinte” sullo stesso URL, l'Endpoint .md dedicato genera un URL pubblico e separato per ogni pagina (ad esempio https://yoursite.com/your-page.md).

Per garantire la massima compatibilità e un fast bot discovery, Crusco Agentic Content segue lo standard RFC 8288 e inserisce il collegamento all'URL alternativo sia come tag  <link> nel codice HTML delle pagina, sia nell'intestazione HTTP della stessa. In questo modo, i crawler intercettano la presenza dell'endpoint .md all'istante e con qualsiasi metodo di scansione.

L'analisi dei comportamenti dei bot evidenzia infatti che i crawler non si comportano tutti allo stesso modo: alcuni negoziano il formato all'interno dello stesso indirizzo, mentre altri preferiscono cercare attivamente i riferimenti a un file Markdown esterno.

Attivando questa opzione, offri piena compatibilità con tutti i bot IA che preferiscono scoprire e navigare i file .md tramite URL diretti.

Guidare gli LLM con lo YAML Front Matter

I modelli linguistici (LLM) interpretano i contenuti con molta più precisione se il contesto e i metadati della pagina sono dichiarati esplicitamente fin dalle prime righe. Abilitando l'opzione “Front Matter”, Crusco Agentic Content ottimizza l'avvio della scansione posizionando, in cima a ogni file Markdown, un blocco YAML Front Matter.

Sebbene il JSON-LD sia lo standard di riferimento per il web semantico dei motori di ricerca tradizionali (come Google), i Large Language Models digeriscono lo YAML in modo nativo e con un'efficienza nettamente superiore.

L'integrazione dello YAML Front Matter offre due benefici strategici:

• Parsing nativo e ottimizzazione dei token: lo YAML riduce al minimo il “rumore” sintattico eliminando le parentesi graffe, le virgolette e le formattazioni nidificate tipiche del JSON-LD. Questo si traduce in un drastico risparmio di token. In pochissime righe, il plugin racchiude l'identità dell'autore (fondamentale per i criteri E-E-A-T), il tipo di schema, la freschezza temporale e le tassonomie di Joomla, permettendo ai modelli di assimilare i dati al volo.
• Semantic Routing per sistemi RAG: i metadati puliti ottimizzano i processi di instradamento semantico delle architetture RAG. Consentono infatti agli agenti IA di filtrare, catalogare e validare la fonte all'istante, determinandone l'autorevolezza e la pertinenza prima ancora di avviare il chunking del testo.

Con questa opzione attiva, Crusco Agentic Content dota ogni risorsa Markdown di una vera e propria carta d'identità semantica, massimizzando l'efficacia con cui il tuo sito Joomla viene letto, indicizzato e citato dai moderni motori di ricerca IA.

Modalità YAML

Quando l'opzione “Front Matter” è attiva, Crusco Agentic Content rende disponibili quattro modalità di formattazione per lo YAML Front Matter. Tre preset e una personalizzata:

• 🛡️ Accurata:

  Massima precisione. Struttura completamente espansa. Riduce al minimo il rischio di allucinazioni dell'IA fornendo una chiara separazione tra ogni singolo punto dati. È la scelta più sicura per i dati complessi.

• ⚖️ Bilanciata:

  Il compromesso ideale. Comprime gli elenchi semplici per risparmiare token, mantenendo una chiara struttura gerarchica. Eccellente equilibrio tra costi di elaborazione e comprensione strutturale.

• 💰 Token Saver:

  Grandi volumi di dati / Budget ridotto. Massima densità di dati per il minimo consumo di token. Consigliato solo per contenuti lineari, poiché l'estrema densità può aumentare il rischio di omissioni di parsing o allucinazioni dell'IA.

• 👤 Personalizzata:

  Definito dall'utente. Decidi tu come viene eseguito il dump dello YAML. Scegli questa modalità se desideri il pieno controllo sulla formattazione del Front Matter impostando i parametri:

  • Inline: il livello gerarchico in cui si passa allo YAML inline
  • Rientro: il numero di spazi da utilizzare per l'indentazione dei nodi annidati.

Campi obbligatori

Sono i campi di cui uno YAML Front Matter che si rispetti, non può fare a meno. Vengono valorizzati tutti automaticamente dal plugin.

• title: il titolo del contenuto. È il corrispettivo del tag h1 e sostituisce l'intestazione 1 (#) nel Markdown. Come da specifica, quando è attivo un Front Matter che contiene il campo title, nel Markdown non può esserci anche l'intestazione 1 (#).
• description: è la sintesi del contenuto e corrisponde al meta tag description tanto caro alla SEO.
• lang: fondamentale per classificare immediatamente la lingua del contenuto (it-IT, en-GB, ecc).
• canonical_url: è l'URL che apparirà nella lista delle “fonti” quando gli LLM risponderanno ai prompt. Nel migliore dei casi, se presente nella pagina HTML, corrisponde all'URL nel link rel="canonical".

Campi delle relazioni di paginazione

Questa opzione serve a istruire le IA su come “sfogliare” correttamente i contenuti multipagina (es. lista di articoli per categoria, articolo diviso in più pagine).

Se nella pagina HTML originale sono stati inseriti correttamente i valori di relazione di pagina rel="next" e rel="prev", Crusco Agentic Content li userà per generare i campi next e prev da inserire nel Front Matter.

Campi opzionali

Crusco Agentic Content ti permette di inserire automaticamente nel Front Matter YAML altre informazioni per aiutare i modelli linguistici a classificare e citare correttamente i tuoi contenuti.

• type: l'inquadramento semantico generale del contenuto. Viene estrapolato dal parsing dello Schema Markup della pagina HTML. Questi i tipi riconosciuti e supportati:
  • AdvertiserContentArticle
  • Article
  • Blog
  • BlogPosting
  • Book
  • ComicStory
  • Course
  • CreativeWork
  • Diet
  • DiscussionForumPosting
  • Event
  • Guide
  • HowTo
  • JobPosting
  • MobileApplication
  • NewsArticle
  • Product
  • Recipe
  • Report
  • SatiricalArticle
  • ScholarlyArticle
  • SocialMediaPosting
  • SoftwareApplication
  • TechArticle
  • Thesis
  • VideoGame
  • WebApplication
  • WebPage
• category e tags: le tassonomie Joomla che aiutano a comprendere il contesto.
• date e lastmod: data di pubblicazione e data di ultima modifica del contenuto. Indicano la freschezza temporale dello stesso.
• image: il path all'immagine rappresentativa del contenuto, che gli LLM possono usare nelle citazioni. Se presente, viene usata l'intro image, altrimenti la full image.
• author: viene usato dagli LLM anche come modello di giudizio sulla qualità dei contenuti e dell’autore (o del sito in generale). Di base contiene il nome dell'autore dell'articolo, ma se nello Schema Markup della pagina HTML sono presenti altri dati inerenti l'autore, vengono anch'essi estrapolati e riportati del Front Matter per incrementare l'E-E-A-T.

  Per questo motivo è consigliato inserire per l'autore, almeno questi dati:

  • Nominativo
  • Foto
  • Professione
  • Una breve biografia
  • Link al sito/blog personale
  • Link ai social media.

Creare un Markdown perfetto

Crusco Agentic Content genera automaticameante il Markdown delle pagine HTML già con le impostazioni di default.

Ma ogni sito fa storia a sé: CSS, struttura, framework, estensioni utilizzate.
Per avere un Markdown perfetto e pulito, che azzeri le allucinazioni e trasformi i tuoi testi nel cibo preferito dagli agenti IA, bisogna agire sui dettagli.

Ecco perché Crusco Agentic Content ti permette di avere il pieno controllo sui contenuti serviti ai modelli.

H1 di riserva

La presenza del tag <h1> nei documenti HTML è fondamentale, sia per la struttura del documento stesso, che ai fini del posizionamento SEO.

Nella conversione in Markdown, tale importanza viene ereditata per GEO e AEO. Il tag <h1> diventerà l'intestazione di livello 1 (#) nel Markdown, oppure, in presenza del Front Matter, il campo title di quest'ultimo. Se questo tag principale è assente dal corpo della pagina HTML, il Markdown corrispondente sarà senza identità.

Per ovviare a quest'eventualità, Crusco Agentic Content ti offre due opzioni per cercare e selezionare un tag <h1> di riserva:

• Scansiona le posizioni della pagina, poi usa il tag <title>.

  Su molti siti il tag <h1> non è posto direttamente nel corpo dell'articolo ma in una posizione di template diversa (banner, top, above component, ecc). Ad esempio, per il sito HTML Crusco è stato inserito in un modulo nella posizione banner per sfruttare la larghezza full-width e per applicare determinati stili grafici.

  Scegliendo questa opzione, la “riserva” sarà cercata inizialmente in tutte le posizioni di template della pagina. Se non viene trovata neanche lì, allora si userà il tag <title>, sicuramente presente.

• Usa direttamente il tag <title>.

  Con questa opzione stai dicendo: Niente ricerche altrove. Se non c'è nel corpo della pagina, allora abbiamo dimenticato di inserirlo. Usa il tag <title> e siamo apposto!

Crea ancore

Le ancore servono per la navigazione in-page. Se hai una pagina con più sezione e una TOC (Table of Contents), avrai di sicuro delle ancore che ti permettono di spostarti in maniera rapida da una sezione all'altra.

In HTML le ancore possono essere agganciate a qualsiasi elemento dotato di id. In Markdown la situazione è più complessa: piattaforme diverse possono avere una diversa gestione delle ancore.

Nel nostro caso, non sapendo a priori né il modello al quale andrà in pasto il Markdown, né lo standard che adotta per le ancore, dobbiamo basarci sulla tabella dell'articolo Markdown Anchor Links: Complete Guide to In-Page Navigation e utilizzare l'approccio più universale possibile.

Non ti preoccupare. Se attivi l'opzione “Crea ancore”, puoi continuare a utilizzare le ancore in HTML come hai sempre fatto... alla loro trasformazione nella versione cross-platform per il Markdown ci penserà Crusco Agentic Content!

Elabora i tag multimediali

Il Markdown non ha una sintassi nativa per i tag <video> e <audio>. Per questo, come succede per le ancore, piattaforme diverse possono gestirli diversamente.

Se attivi questa opzione, i tag multimediali vengono convertiti in Thumbnail Link, una rappresentazione Markdown multipiattaforma ideale per l'IA.

Se non attivi questa opzione e le tue pagine HTML contengono ad esempio il tag video, nel Markdown potrebbe finire un testo indesiderato come questo: “Your browser does not support the video tag”. Se non ti interessa avere la conversione in Markdown dei video, ma vuoi comunque evitare questi inconvenienti, puoi modificare l'opzione “Rimuovi nodi prima dell'erogazione” aggiungendo “video” alla lista predefinita:

Elabora i tag map

Lo scopo di Crusco Agentic Content è quello di migliorare il tasso di citazione dei tuoi contenuti nelle risposte dell'IA, e lo fa senza risparmiarsi.

Nonostante i tag <map> e <area> non abbiano un corrispettivo in Markdown, attivando questa opzione il plugin processerà questi tag nelle tue pagine HTML trasformandoli in un blocco di testo semantico e strutturato, una rappresentazione Markdown che i modelli linguistici ingurgiteranno per capire la mappa immagine e aumentare la loro comprensione dei contenuti.

Rimuovi immagini Base64

Se i motori di ricerca tradizionali tollerano senza problemi le immagini Base64 (quelle incorporate direttamente nel codice), i nuovi sistemi di Intelligenza Artificiale reagiscono invece in maniera diversa. Quando trasformi una pagina web in un file Markdown per darlo in pasto a un'IA, la presenza di immagini incorporate crea tre problemi immediati:

• Cecità dell'IA: l'immagine scompare

  I modelli IA cercano URL standard per attivare la loro pipeline visiva. La sintassi Base64 in Markdown non viene decodificata automaticamente. L'IA non “vede” l'immagine, ma percepisce solo un blocco di testo corrotto, ignorando il contenuto visivo.

• Spreco di token: il rumore di fondo

  Il Markdown serve a risparmiare token isolando il testo puro. Una singola immagine Base64 inietta nel file fino a 80.000 token testuali spazzatura. Questo sovraccarico satura la memoria del modello (Context Window) e distorce l'algoritmo di attenzione, causando risposte imprecise o allucinazioni.

• RAG in tilt: database vettoriali corrotti

  I sistemi RAG spezzettano il Markdown in piccoli frammenti (chunking) per indicizzarli. Il Base64 riempie decine di questi blocchi con stringhe alfanumeriche prive di significato semantico. Questo inquina gli embedding e il database, spingendo il bot a restituire codice impazzito agli utenti.

Attivando l'opzione “Rimuovi immagini Base64” eviterai alla radice questi problemi: Crusco Agentic Content eliminerà automaticamente dall'HTML le immagini incorporate, prima di convertire i tuoi contenuti in Markdown.

Rimuovi elementi nascosti

Mentre nell'HTML i contenuti nascosti possono servire a gestire l'interazione con l'utente, nel Markdown aumentano solo il payload del file. I bot IA leggono tutto il testo indistintamente, consumando token inutili.

Attivando “Rimuovi elementi nascosti”, Crusco Agentic Content eliminerà tutti gli elementi nascosti tramite stili CSS in linea (display: none, opacity: 0, ecc), garantendo un Markdown più snello e ottimizzato.

Rimuovi elementi tramite selettore CSS

Crusco Agentic Content rimuove già di default gli elementi strutturali standard della pagina, come header e footer, isolando così il valore reale dei contenuti.

Questa opzione ti permette in più di eliminare elementi personalizzati. Inserendo i relativi selettori CSS, puoi ripulire il layout da moduli di Joomla, estensioni di terze parti o blocchi inutili per il Markdown, come il banner dei cookie, i sistemi di captcha, i box dei commenti o le icone di stampa.

È lo strumento ideale anche per eliminare dati ridondanti, come ad esempio il box autore: poiché Crusco Agentic Content inserisce già tutti i dettagli dell'autore (bio, foto, social) in modo strutturato nello YAML Front Matter, puoi usare il selettore per rimuoverli dal corpo del testo, evitando i duplicati e servendo così agli LLM un Markdown più leggero.

Appendi blocco JSON-LD grezzo

Attiva questa opzione solo se hai veramente bisogno di ogni singolo dato contenuto all'interno dello schema markup, anche a discapito di una migliore ottimizzazione del contenuto per l'IA.

Viceversa, puoi lasciarla disabilitata se hai attivato lo YAML Front Matter: quest'ultimo contiene già una selezione dei metadati più importanti, viene digerito nativamente dagli LLM e garantisce un'efficienza nettamente superiore.

Ignora componenti

Potresti non avere la necessità di attivare il Markdown su ogni sezione del tuo sito web.
Un esempio?

Le pagine di login e registrazione. Oppure pagine generate da componenti che non rispettano gli standard di Joomla e che in formato Markdown potrebbero risultare insignificanti (o deleterie).

Attraverso questa opzione puoi scegliere quale escludere.

Definire l'AI Policy

L'utilizzo dei dati da parte dei modelli linguistici è al centro del dibattito sul diritto d'autore.
Con la sezione AI Policy di Crusco Agentic Content riprendi il controllo dei tuoi contenuti, impostando regole chiare per i tuoi contenuti HTML e Markdown nel tag <head> e nell'intestazione HTTP. Opzionalmente puoi estendere queste regole anche a tutte le risorse del sito, come immagini, PDF e video.

Utilizzo dei contenuti

Questa opzione ti permette di definire il livello di protezione dei tuoi testi in piena conformità con l'Articolo 53 dell'EU AI Act, che obbliga legalmente i fornitori di intelligenza artificiale a rispettare la riserva del diritto d'autore espressa tramite strumenti leggibili dalla macchina (machine-readable means).

Per garantire la massima sicurezza, il plugin attiva contemporaneamente due diversi standard globali: il protocollo TDMRep, lo standard ufficiale ratificato dal W3C per la tutela del copyright europeo, e la sintassi dei Content Signals (un'iniziativa aperta e promossa da Cloudflare e Thoughtworks, attualmente in fase di discussione presso l'IETF per la ratifica ufficiale, ma che è già uno standard de facto adottato e rispettato dai principali crawler globali).

Scegliendo tra le due modalità disponibili, configurerai automaticamente l'accesso per i bot:

• Consenti AI Input: indica ai sistemi di IA (come Perplexity o ChatGPT Search) che possono leggere le tue pagine esclusivamente per rispondere in tempo reale alle domande immediate degli utenti (sistemi RAG). Al tempo stesso, vieta categoricamente l'ingestione, lo scraping e la memorizzazione dei tuoi testi nei dataset per l'addestramento futuro o per il fine-tuning dei modelli commerciali delle big tech.
• Consenti AI Input & AI Training: concede l'autorizzazione estesa e permanente di sfruttare i tuoi contenuti editoriali per qualsiasi finalità, inclusi lo scraping di massa per la creazione di dataset e l'addestramento dei modelli commerciali.

URL della Policy TDM

Questo parametro opzionale risponde al quadro normativo dell'EU AI Act e della Direttiva Europea sul Diritto d'Autore (CDSM).
Permette di allegare un URL alle tue risposte di rete per indicare formalmente ai crawler le condizioni di utilizzo dei tuoi contenuti.

Perché questa preferenza venga interpretata correttamente dai sistemi automatizzati, il file di policy deve essere strutturato in formato machine-readable seguendo lo standard del profilo ODRL descritto nella specifica ufficiale del W3C.

Puoi fare riferimento alle linee guida e agli esempi di codice ufficiali consultando la documentazione alla sezione W3C TDM Policy Specification. È lo strumento ideale per le organizzazioni che desiderano negoziare accordi di licenza o indicare ai bot commerciali i propri contatti legali.

Direttive sui link nel Markdown

Controlla il modo in cui gli agenti IA elaborano i collegamenti ipertestuali scoperti all'interno del payload Markdown.

• Follow: permetti agli LLM di seguire i link per approfondire il topic, scoprire nuove risorse e citare correttamente le tue fonti.
• Nofollow: indichi ai bot di ignorare i link, impedendo un'ulteriore scansione da quella pagina per proteggere la tua rete di collegamenti.

Naturalmente viene rispettata l'eventuale blindatura presente nella pagina originale HTML.
Se su questa è presente una direttiva <nofollow>, sarà replicata anche nella versione Markdown del contenuto, a prescindere dalle impostazioni dell'opzione in oggetto.

Endpoint .well-known/tdmrep.json

Per impostazione predefinita, Crusco Agentic Content applica le regole AI policy sull'utilizzo dei contenuti solo alle pagine HTML ed il loro corrispettivo Markdown.

Attivando invece questa opzione, tali regole saranno scritte anche nell'endpoint .well-known/tdmrep.json, indicando alle IA che le restrizioni sull'utilizzo dei tuoi contenuti sono globali, e si applicano anche a tutti i file statici, come ad esempio immagini, video, font e PDF.

Visualizzare il Markdown servito all'IA

Parametro “markdown” sull'URL

Aggiungi il parametro markdown=1 a qualsiasi indirizzo di pagina html del tuo sito web.

https://yoursite.com/your-page-url?markdown=1

Questo metodo funziona indifferentemente dal metodo di erogazione abilitato (Content Negotiation e/o Endpoint .md dedicato), a meno che tu non stia tentando di visualizzare il Markdown per uno dei componenti che hai escluso dalle opzioni del plugin. In questo caso riceverai un errore 404.

curl per simulare la richiesta di Markdown di un bot IA

Se hai abilitato la “Content Negotiation” e sulla tua periferica hai installato curl, puoi utilizzarlo per forzare la richiesta del formato Markdown:

curl -si -LH "Accept: text/markdown" https://yoursite.com/your-page-url

In questo modo visualizzerai sia le intestazioni HTTP che l'output in Markdown.

Endpoint .md

Se nelle opzioni del plugin hai attivato l'opzione “Endpoint .md dedicato”, puoi visualizzare il Markdown utilizzando il suo indirizzo.
Lo trovi visualizzando il sorgente o le intestazioni HTTP della tua pagina HTML tramite il Network Inspector di qualsiasi browser. Dovrebbe avere questo formato:

<link href="https://yoursite.com/your-page-url.md" rel="alternate" type="text/markdown" data-generator="Crusco Agentic Content Pro">

Incolla l'indirizzo nel browser e vedrai il Markdown:

https://yoursite.com/your-page-url.md

Screenshot del plugin