Skip to content

🐙 Gestione e Indicizzazione tramite GitHub

Il backend della nostra piattaforma si basa su un'architettura orientata ai file. Per aggiungere, modificare e indicizzare correttamente un file appena caricato, l'infrastruttura di riferimento si trova nel seguente percorso della repository:

src/content/docs/

📁 Cartelle di Riferimento

All'interno del percorso src/content/docs/, le directory principali destinate all'inserimento e all'indicizzazione dei file sono:

  • documenti/
  • manga/
  • serie/
  • sezioni/

🤖 Mappatura e Percorsi dei File

L’indice del sito può essere aggiornato rapidamente tramite il bot Admin Utility utilizzando il comando /github (il sistema guiderà la procedura richiedendo anche l'inserimento di eventuali TAG).

Tuttavia, poiché questo strumento nasce esclusivamente per scopi di catalogazione rapida, sono presenti alcune precise limitazioni operative. Le uniche azioni NON consentite tramite il bot sono:

  • Scrivere un intero documento o tutorial: Il bot permette di indicizzare una guida all’interno del sistema, ma non può essere utilizzato per redigerne o memorizzarne il contenuto testuale effettivo.
  • Gestire il dettaglio dei manga: È possibile inserire l’opera nell’indice generale tramite il bot, ma non si ha la possibilità di creare o compilare il file specifico contenente l’elenco dettagliato dei singoli volumi.

🎬 Aggiornamento Indice per Episodi e Stagioni (Serie/Anime)

Se devi aggiornare l'indice di singole serie o anime, la procedura varia a seconda della presenza o meno del contenuto sul server:

  • Serie già presente nell'indice: Invia il video direttamente al BOT inserendo nel nome del file o nella didascalia il formato standard NomeSerie SxEy. Al primo invio, il BOT richiederà l'associazione del file .mdx corretto tramite dei pulsanti a schermo: basterà selezionare quello giusto. Se invii più episodi contemporaneamente, il BOT memorizzerà l'associazione per i file successivi, aggiornerà l’indice su GitHub e inoltrerà il video nel gruppo in modo totalmente automatico.
  • Serie completamente nuova: Una volta arrivati alla fase di selezione del file .mdx, il BOT rileverà la novità e ti permetterà di creare direttamente il nuovo file da zero, generandolo già formattato in maniera corretta.

📄 Gestione dei File .mdx

I file del server utilizzano l’estensione .mdx, ma la loro gestione è estremamente intuitiva e non richiede competenze avanzate di programmazione.

💡 Regola del Modello: Per aggiornare o creare una nuova scheda non serve reinventare la struttura da zero. È sufficiente aprire un file già esistente nella stessa directory, prenderlo come modello e replicare la stessa sintassi nel nuovo documento, modificando semplicemente i campi variabili (come il titolo, il numero degli episodi e i relativi link di download).

🚀 Monitoraggio del Deployment e Controllo Qualità

Una volta salvate e inviate le modifiche al file (tramite commit), GitHub avvierà automaticamente il processo di compilazione e aggiornamento del sito. Puoi monitorare lo stato dell’operazione direttamente dall’interfaccia di GitHub attraverso tre indicatori visivi:

  • "🟠 Pallino Arancione" Indica che i server stanno elaborando le modifiche e compilando i contenuti del sito. Il processo richiede solitamente tra i 2 e i 4 minuti.

  • "🟢 Spunta Verde" Conferma che la compilazione è andata a buon fine e che le modifiche sono state pubblicate correttamente online.

  • "🔴 'X' Rossa" Segnala che si è verificato un errore di sintassi o di formattazione durante l’aggiornamento del file, bloccando il deployment. In questo caso è necessario riaprire il file modificato, individuare l'errore (spesso un tag chiuso male, un'indentazione errata o un link interrotto) e correggerlo.

⚠️ Verifica Manuale: Al termine di ogni operazione, non limitarti al feedback visivo di GitHub. Effettua sempre un controllo manuale direttamente sul sito web per assicurarti che la nuova risorsa sia visibile, che i link funzionino correttamente e che l’impatto grafico sia ottimale.

🏷️ Gestione dei Tag e Standard di Caricamento

Per evitare di sovraccaricare i titoli con informazioni superflue, abbiamo stabilito dei criteri di base sia per Telegram sia per GitHub. In presenza di determinati standard di sistema, di lingua o di formato, il file deve essere considerato "pulito" e non richiede l’inserimento di alcun tag.

📋 Standard di Base (Senza Tag)

  • Software e Applicativi: La versione per sistemi operativi Windows rappresenta lo standard della community, pertanto non necessita di tag.
  • Contenuti Video (Film, Serie TV, Anime): Lo standard prevede che la traccia audio principale sia in lingua italiana; in questo caso il tag va omesso.
  • Documentazione e Guide: Il formato predefinito per la condivisione di testi, manuali o guide è il file PDF, che di conseguenza non richiede alcuna specifica nel titolo.
  • Videogiochi: Lo standard di riferimento è la versione nativa per PC (Windows), che non ha bisogno di tag.

🚨 Eccezioni Obbligatorie (Richiedono il Tag)

  • Contenuti Video con Sottotitoli: La presenza di sottotitoli costituisce un’eccezione fondamentale che va sempre esplicitata utilizzando il tag dedicato (ad esempio inserendo [SUB ITA], anche qualora si tratti di sottotitoli nella nostra lingua).
  • Videogiochi in Realtà Virtuale: È obbligatorio isolare e segnalare i titoli che richiedono l’utilizzo di un visore inserendo il tag specifico [PCVR].

🎨 Utilizzo Manuale dei Badge su GitHub

Se utilizzi il BOT per indicizzare i file, i codici per inserire i Badge/TAG non ti servono poiché la conversione viene gestita in automatico.

Se invece stai operando un aggiornamento manuale direttamente sui file di GitHub, utilizza la sintassi dei componenti integrati rispettando questa associazione cromatica:

  • 🔴 ROSSO per le estensioni dei file ([EPUB], [CBR], ecc.): html <Badge text="EPUB" variant="danger"/>

  • 🟡 GIALLO per la lingua e i sottotitoli ([ENG], [GER], [SUB ITA]): html <Badge text="GER" variant="caution"/>

  • 🔵 BLU per le informazioni di base e sistemi operativi ([ANDROID], [MAC]): html <Badge text="Android" variant="note"/>

(Nota: All'interno del codice del badge, sostituisci il testo del parametro text="..." con l'esatto tag che intendi mostrare a schermo).

NON HAI BISOGNO DI SAPERE COME USARE I TAG SE USATE IL BOT PER INDICIZZARE