Panoramica delle funzionalità

Rendering#

Sintassi Markdown#

Oltre a CommonMark e GitHub Flavored Markdown, sono supportate anche queste estensioni:

Matematica#

Il rendering è affidato a KaTeX , molto più veloce di MathJax.

• In linea: $E = mc^2$ oppure \(E = mc^2\)
• A blocco: $$…$$ oppure \[…\]
• Matrici, allineamenti multilinea aligned, funzioni a tratti cases, somme e integrali, lettere greche e simboli dei pacchetti più comuni

Il lettore protegge il carattere $, quindi prezzi come $100 e $5 - $10 non vengono scambiati per formule.

Diagrammi#

Il rendering è affidato a Mermaid : basta scrivere il diagramma in un blocco di codice ```mermaid. Sono supportati diagrammi di flusso, sequenza, classe, stato, ER, Gantt, torta, percorso utente, mappe mentali, grafi Git, quadranti e timeline.

I temi dei diagrammi sono collegati alle variabili del tema del sito: passando alla modalità scura, i diagrammi vengono ridisegnati con colori coordinati. Passa il mouse su un diagramma per copiarne il sorgente o scaricare l’SVG dall’angolo in alto a destra.

Evidenziazione della sintassi#

• Chroma evidenzia sul server (pagine della documentazione); highlight.js evidenzia sul client (lettore). Entrambi usano le stesse variabili colore, quindi il risultato è identico
• Ogni blocco di codice offre etichetta del linguaggio, pulsante di copia, interruttore dei numeri di riga e interruttore del ritorno a capo
• I blocchi più lunghi di 24 righe vengono compressi automaticamente; fai clic per espanderli
• Un attributo title può indicare il nome del file:

1
2
3

```js {title="app.js"}
const a = 1;
```

Riquadri informativi#

Sono supportate entrambe le notazioni. Stile GitHub (disponibile nella documentazione e nel lettore):

1
2
3
4
5
6
7
8

> [!NOTE]
> Un’osservazione generale

> [!TIP]
> Un suggerimento pratico

> [!WARNING]
> Qualcosa a cui prestare attenzione

Stile contenitore (solo nel lettore; le pagine della documentazione non lo analizzano):

1
2
3

::: tip Titolo personalizzato
La sintassi del contenitore supporta note / tip / important / warning / caution / danger / details
:::

Sei tipi: NOTE TIP IMPORTANT WARNING CAUTION DANGER.

Front matter#

Sono riconosciuti YAML (---), TOML (+++) e JSON ({}). title, description, date, author, tags e categories vengono mostrati nell’intestazione del documento; tutto il resto viene raccolto in una scheda “Front matter”.

Comfort di lettura#

Temi#

• Chiaro, scuro e sistema; premi D per cambiare ciclicamente
• Uno script in linea applica il tema prima del primo rendering, quindi non compare alcun lampo bianco
• In modalità scura i colori di codice, diagrammi e formule si adattano insieme

Tipografia#

Premi , per aprire il pannello delle impostazioni:

Le impostazioni vengono salvate nel localStorage del browser e persistono tra pagine e sessioni.

Navigazione#

• Albero dei file: directory comprimibili con filtro istantaneo per nome file
• Indice: livelli da 2 a 4; usa IntersectionObserver per evidenziare la sezione corrente durante lo scorrimento e scorre a sua volta per seguirla
• Avanzamento di lettura: una barra sfumata in alto e un pulsante per tornare in cima dopo 600 px
• Memoria della posizione: la posizione di scorrimento di ogni documento viene salvata come rapporto e ripristinata al ritorno
• Precedente / successivo: J e K scorrono l’elenco dei file

Immagini#

Fai clic per aprire il visualizzatore: scorri per zoomare, trascina per spostare, fai doppio clic per alternare 1×/2×, usa + - 0 da tastiera oppure scarica direttamente l’immagine.

Ricerca#

Ricerca tra file nel lettore#

Premi / oppure Ctrl+K. Una volta caricata una cartella, ogni file Markdown viene letto in background per creare un indice fuzzy con Fuse.js , ponderato titolo > nome file > testo > percorso. I risultati mostrano il percorso e un estratto contestuale evidenziato; le frecce selezionano, Invio apre.

Ricerca nel documento#

Premi F oppure Ctrl+F per evidenziare una alla volta le corrispondenze nel documento corrente. Invio passa alla successiva, Shift+Invio alla precedente, con un contatore “n di m”.

Ricerca nell’intero sito#

Le pagine della documentazione vengono indicizzate in anticipo, così la casella di ricerca interroga l’indice interamente nel browser, senza richieste a un backend.

Modifica#

Premi M per entrare in modalità modifica: sorgente Markdown a sinistra e anteprima dal vivo a destra (con debounce di 260 ms), separati da un divisore trascinabile la cui posizione viene ricordata nelle impostazioni.

• Barra degli strumenti: titoli, grassetto, corsivo, barrato, codice in linea, tre tipi di elenco, citazione, collegamento, immagine, tabella, blocco di codice, formula, Mermaid, riquadro informativo e linea orizzontale. Fai di nuovo clic per rimuovere una formattazione già applicata
• Tastiera: Ctrl+B/I/K per grassetto, corsivo e collegamento; Tab indenta una selezione multilinea; Invio continua un elenco incrementando il numero e lo termina se premuto su una voce vuota. Ogni operazione passa attraverso execCommand, quindi lo stack di annullamento nativo del browser continua a funzionare
• Salvataggio: Ctrl+S scrive nel file locale originale. Al primo salvataggio il browser chiede l’autorizzazione, estendendo il precedente permesso di sola lettura a lettura e scrittura
• Bozze: il contenuto viene salvato in IndexedDB dopo 1,2 s di inattività. Passare a un altro file, chiudere l’area di lavoro o chiudere la pagina richiede conferma in presenza di modifiche non salvate; alla riapertura del file viene proposto il ripristino della bozza
• Cache Mermaid: l’anteprima memorizza i diagrammi renderizzati in base al sorgente, così la digitazione non li ridisegna ripetutamente

Esportazione#

L’esportazione PDF consente di impostare formato carta (A4 / Letter / A5), orientamento, margini, scala del testo, pagina del titolo, indice cliccabile, interruzione di pagina a ogni H1 o H2, ritorno a capo del codice e stampa degli URL esterni. In modalità scura i diagrammi Mermaid vengono temporaneamente ridisegnati con colori chiari, per evitare di stampare testo pallido su uno sfondo scuro.

Come funziona#

Dipendenze e dimensioni#

Ogni dipendenza viene inclusa nell’output durante la build, quindi in fase di esecuzione non viene contattata alcuna CDN di terze parti. Il sito può essere distribuito completamente offline e nessuna risorsa esterna può essere bloccata.

Privacy#

• Tutte le operazioni di lettura e scrittura avvengono nel browser; non viene mai caricato nulla
• Nessuno script di terze parti, nessuna analisi, nessun tracciamento, nessun cookie
• Le impostazioni risiedono in localStorage; handle delle directory, posizioni di lettura e bozze di modifica risiedono in IndexedDB, tutto sul tuo computer

Lingue#

L’interfaccia è disponibile in inglese, cinese semplificato, cinese tradizionale, giapponese, spagnolo, francese, italiano e tedesco. L’inglese si trova alla radice; le altre lingue usano /zh/, /zh-hant/, /ja/, /es/, /fr/, /it/ e /de/, ciascuna con un proprio URL condivisibile. L’icona del globo nell’intestazione permette di cambiare lingua in qualsiasi momento, raggiungendo la traduzione corrispondente della pagina corrente quando disponibile.

Le stringhe dell’interfaccia risiedono in data/i18n/<lang>.toml e sono condivise tra template e script del browser; ogni pagina carica soltanto le stringhe della propria lingua. Alla prima visita, se la lingua del browser è diversa da quella della pagina, in basso compare una richiesta di cambio lingua, che può essere disattivata definitivamente.

Collegamenti correlati#

• Esempi della sintassi Markdown
• Scorciatoie da tastiera