Allegati della documentazione

Allega immagini e file direttamente a qualsiasi pagina di documentazione. Trascina uno screenshot nell'editor e viene incorporato nel testo; allega un PDF, una specifica o un archivio e compare come scheda scaricabile. I file vengono salvati in un object storage, senza mai appesantire il database, e accompagnano la pagina ovunque venga visualizzata o condivisa.

Aggiungere allegati

Apri una pagina di documentazione nell'editor (Nuovo documento o Modifica) e aggiungi i file nel modo più rapido per te:

  • Trascina e rilascia uno o più file sull'editor
  • Incolla un'immagine direttamente dagli appunti (ad esempio uno screenshot)
  • Clicca su Allega file nella barra degli strumenti dell'editor e scegli i file

Puoi allegare più file contemporaneamente. Un nuovo documento viene salvato automaticamente la prima volta che alleghi un file, così non perdi mai un caricamento.

Immagini e file

Archyl gestisce i due casi come ti aspetteresti:

  • Le immagini vengono incorporate nel testo del tuo Markdown nel punto in cui le aggiungi, così vengono visualizzate direttamente nella pagina.
  • Gli altri file (PDF, documenti, archivi, …) vengono aggiunti al pannello Allegati come schede scaricabili invece di essere inseriti nel testo.

Visualizzare gli allegati

Durante la lettura di una pagina, gli allegati compaiono in un pannello Allegati in cima al documento, subito sotto il titolo, così chi legge vede cosa è disponibile prima di scorrere. Per ogni file vengono mostrati:

  • Un'icona del tipo con codice colore, oppure una miniatura dell'immagine
  • Il nome, il tipo e la dimensione del file
  • Un'azione di download con un clic

Le immagini vengono inoltre visualizzate nel testo ovunque tu le abbia inserite nel contenuto.

Gestire gli allegati

Dall'editor, il pannello Allegati ti permette di:

  • Scaricare qualsiasi file
  • Eliminare un file (con una rapida conferma in linea): il file viene rimosso anche dallo storage

Eliminando un documento vengono rimossi anche i suoi allegati.

File supportati

Puoi allegare qualsiasi tipo di file. Le immagini vengono incorporate nel testo; tutto il resto compare come scheda scaricabile. Esempi comuni:

  • Immagini — PNG, JPEG, GIF, WebP, SVG, AVIF
  • Documenti — PDF, Word, Excel, PowerPoint, testo semplice, Markdown, CSV
  • Dati e archivi — JSON, YAML, ZIP, log

Il limite predefinito è di 10 MB per file (configurabile nelle istanze self-hosted).

Suggerimento: se il browser non riconosce un tipo di file, il file viene comunque accettato e proposto come download.

Storage e privacy

Gli allegati risiedono in un object storage anziché nel database dell'applicazione. Su Archyl Cloud, lo storage è Google Cloud Storage, gestito per te e senza nulla da configurare. Nelle istanze self-hosted scegli tu il provider compatibile S3 (vedi sotto).

In entrambi i casi:

  • Il bucket è privato. I file vengono serviti tramite link firmati a breve scadenza, generati su richiesta: gli oggetti sottostanti non sono mai elencabili pubblicamente.
  • I link incorporati in una pagina restano stabili, quindi la documentazione condivisa e pubblica continua a funzionare senza esporre il bucket.
  • La cifratura a riposo è attiva per impostazione predefinita. Google Cloud Storage cifra automaticamente ogni oggetto; nelle istanze self-hosted puoi anche fornire le tue chiavi (ad esempio una CMEK di Cloud KMS su GCS).

Per le istanze self-hosted

Su Archyl Cloud gli allegati funzionano subito. Se usi Archyl in self-hosting, porti il tuo object storage e puoi collegare Archyl a qualsiasi provider compatibile S3 (Google Cloud Storage, Amazon S3, MinIO, Cloudflare R2, …).

Finché lo storage non è configurato, l'azione Allega file non è disponibile e i caricamenti restituiscono un messaggio esplicito, "File storage is not configured". Imposta le variabili d'ambiente STORAGE_* sul backend (endpoint, bucket, access key, secret key) per abilitare la funzionalità; per Google Cloud Storage, usa l'endpoint di interoperabilità (HMAC). Consulta la configurazione del tuo deployment per l'elenco completo delle opzioni.

Prossimi passi