bookish/docs/wiki.md

Wiki di Bookish

Guida all'uso

Convertitore

1. Apri la homepage di Bookish
2. Trascina un file nell'area di upload, oppure clicca per selezionarlo
3. Scegli il formato di destinazione cliccando su un bottone
4. Clicca Converti
5. La barra di progresso mostra lo stato della conversione
6. A conversione completata, clicca Scarica file
7. Opzionale: clicca Leggi nel reader per visualizzare il file convertito

Formati supportati

Input	Output
EPUB	EPUB, MD, DOCX, PDF, TXT, HTML, FB2, LaTeX
PDF	EPUB, MD, DOCX, TXT, HTML, LaTeX
DOCX	EPUB, MD, PDF, TXT, HTML, LaTeX
Markdown	EPUB, DOCX, PDF, TXT, HTML, LaTeX
TXT	EPUB, MD, DOCX, PDF, HTML, LaTeX
HTML	EPUB, MD, DOCX, PDF, TXT, LaTeX
FB2	EPUB, MD, DOCX, PDF, TXT, HTML, LaTeX
LaTeX	EPUB, MD, DOCX, PDF, TXT, HTML

Reader — Operazioni base

1. Vai su Reader nella navigazione

2. Trascina un ebook (EPUB, PDF, MD, TXT, HTML, FB2, DOCX) o clicca per caricarlo

3. Usa la toolbar per:

   Pulsante	Azione
   ☰	Apri/chiudi indice laterale
   ⇔	Slider larghezza area di lettura (40–100%)
   A− / A+	Zoom font
   ☀️ / 🌙 / 🟤	Cambia tema (chiaro/scuro/seppia)
   🔍	Cerca nel testo
   🔖	Aggiungi segnalibro alla posizione corrente
   ⛶	Schermo intero
   ?	Aiuto e scorciatoie da tastiera

4. Naviga con le frecce ← → della tastiera

5. La posizione di lettura viene salvata automaticamente (locale + server)

Reader — Segnalibri

• Premi 🔖 nella toolbar o Ctrl+B / ⌘B per aggiungere un segnalibro
• Un toast di conferma appare in basso e il pulsante fa un piccolo "pulse"
• Vai nella sidebar ☰ → Segnalibri per vedere l'elenco
• Clicca su un segnalibro per tornarci
• Premi ✕ per eliminarlo
• I segnalibri sono salvati su server SQLite + localStorage (fallback)
• Lo stesso libro ha sempre gli stessi segnalibri, anche su PC diverso

Reader — Scorciatoie da tastiera

Tasti	Azione
← / →	Pagina precedente/successiva
Ctrl+B / ⌘B	Aggiungi segnalibro
Ctrl+F / ⌘F	Cerca nel libro
+ / -	Zoom avanti/indietro
F	Schermo intero
Esc	Chiudi help modal / Esci da fullscreen

Reader — Slider larghezza

La barra a destra nella toolbar (con icona ⇔) regola la larghezza dell'area di lettura dal 40% al 100% dello schermo. Utile per file con righe molto lunghe o per preferenze personali di lettura. L'impostazione viene salvata in localStorage.

API Endpoints

Endpoints pubblici

Metodo	Path	Descrizione
POST	/upload	Carica file e avvia conversione
GET	/progress/<task_id>	SSE stream progresso
GET	/download/<filename>	Scarica file convertito
GET	/formats?input=<ext>	Formati disponibili per input
GET	/reader	Pagina reader
GET	/reader/<filename>	Reader per file specifico
GET	/reader/serve/<filename>	Serve il file al reader
GET	/reader/formats	Formati supportati dal reader

API REST (bookmarks e posizioni)

Metodo	Path	Descrizione
GET	/api/bookmarks/<content_hash>	Recupera tutti i segnalibri del libro
POST	/api/bookmarks	Aggiunge un segnalibro
DELETE	/api/bookmarks/<id>	Elimina un segnalibro
GET	/api/position/<content_hash>	Recupera l'ultima posizione di lettura
PUT	/api/position/<content_hash>	Salva la posizione di lettura (body JSON)

Domande frequenti

D: Che qualità ha la conversione? R: Pandoc preserva titoli, grassetto/corsivo, elenchi, tabelle semplici e immagini. Per layout complessi (es. PDF con colonne multiple) la fedeltà dipende dalla complessità del file originale.

D: I file vengono conservati? R: I file in uploads/ e converted/ vengono cancellati dopo 1 ora. Usa il download subito dopo la conversione. I segnalibri e le posizioni di lettura sono invece permanenti in bookish.db.

D: I segnalibri restano se ricarico lo stesso libro? R: Sì. I segnalibri sono legati al contenuto del file (SHA256), non al nome o all'UUID di upload. Stesso file = stessi segnalibri.

D: Posso usare i segnalibri da un altro PC? R: Sì, se sei sulla stessa LAN e raggiungi lo stesso server. I segnalibri sono salvati su SQLite, non nel browser.

D: Quanto spazio serve? R: Minimo. L'app stessa è ~5MB. Pandoc binary incluso ~35MB extra. Il database SQLite occupa pochi KB.

D: Posso usarlo su mobile? R: Il convertitore è responsive. Il reader funziona ma non è ottimizzato per schermi piccoli.

D: Come cambio la secret key? R: Imposta BOOKISH_SECRET come variabile d'ambiente prima di avviare.

Sicurezza

• Uso personale — nessuna autenticazione implementata
• File validati per estensione all'upload
• Path traversal prevenuto con os.path.basename() e secure_filename()
• MIME types controllati al download
• Limite file a 50MB
• Pulizia automatica file temporanei dopo 1h