Il campionario

§1.1Segni in linea

L’analisi dell’enfasi è amichevole col CJK: il grassetto si chiude anche contro la punteggiatura cinese — **报文。**同时 rende 报文。同时, e non asterischi letterali. Il corsivo, il barrato e il codice in linea funzionano come al solito; con l’interruttore gemoji uno shortcode come :sparkles: rende ✨. I caratteri dentro il codice in linea non partecipano ad alcuna analisi, perciò i backtick sono il modo sicuro di mostrare la sintassi: **, $…$ e > [!note] compaiono tutti alla lettera. Per mostrare un asterisco nel discorso, fai l’escape — *così* resta testo semplice.

§1.2Wikilink

Con l’interruttore wikilinks acceso, i link [[a doppie parentesi]] si risolvono sulla collezione di note come un wiki si aspetta: per id (design-tokens — partendo da una pagina mirror italiana si atterra prima sul mirror nella stessa lingua, e solo in sua assenza sull’originale inglese), per alias (boundaries raggiunge la nota il cui id è three-way-split), con un’etichetta (la guida dei primi passi). Un bersaglio che non si risolve rende come link morto marcato invece di far fallire la build — e la CLI check-wikilinks del motore lo riporta in CI, dove la ruggine dei link appartiene.

§1.3Tabelle: scorrono da larghe, si fanno carte da strette

Una tabella con sei o più colonne dovrebbe, in un contenitore stretto, ridisporsi una riga per carta invece di strizzare ogni cella a due caratteri. Questa tabella a sette colonne è insieme il promemoria delle varianti di callout e una verifica dal vivo di quel reflow (stringi la finestra a larghezza di telefono):

I titoli predefiniti sono in inglese; un sito sostituisce l’intera serie con l’opzione calloutLabels di siteMarkdown, per esempio calloutLabels: { tip: 'Intuizione' }. Un titolo scritto nella sintassi a citazione (> [!tip] Il mio titolo) vince sempre.

§2.1Callout: tre grafie

Prima, la sintassi a citazione di Obsidian/GitHub (disponibile con callouts: true, funziona anche nei file Markdown semplici):

Il segno di ripiegatura di Obsidian è rispettato — > [!note]- rende chiuso, > [!note]+ aperto:

Poi, il componente del pacchetto in MDX (astro-inkstone/components/Callout.astro, importato per percorso). Senza title mostra l’etichetta predefinita della variante, la stessa che usa la sintassi a citazione:

Terza, l’HTML a crudo, tutte e sei le varianti in un colpo (in corrispondenza uno-a-uno con le regole .callout di base.css):

§2.2Matematica

Le formule in linea siedono nel testo: la profondità ottica si legge $\tau = \int \kappa \rho \, \mathrm{d}s$. La matematica in display prende la forma su tre righe ($$ su righe proprie) — il guardiano respinge la forma su riga singola, che renderebbe in silenzio come una piccola formula in linea:

Il fondo delle formule è di proposito una carta diversa da quella del corpo, e cambia col tema. Già che ci siamo: nel discorso, ai prezzi in dollari serve l’escape — questo caffè costa $3.

§3.1Cornici di codice

Un blocco con title="…" riceve una barra del titolo col nome del file; il pulsante di copia nell’angolo c’è in tutto il sito. Le annotazioni di riga [!code ++] / [!code --] rendono come fondi diff:

def build_pipeline(opts):
    plugins = [remark_math]  
    plugins = [remark_gemoji, remark_math]  
    return assemble(plugins, guard=opts.guard)

Una cornice marcata collapse parte ripiegata e occupa spazio solo da aperta — giusta per i file di configurazione lunghi:

site:
  markdown:
    numbering: chapters
    math: true
    codeFrame: true
    mermaid: true
    callouts: true
    wikilinks: true
  styles:
    - astro-inkstone/styles/tokens.css
    - astro-inkstone/styles/base.css

L’evidenziazione a doppio tema viene da shiki, che emette entrambe le serie di colori in un colpo solo; base.css ne sceglie una in base a data-theme, in un punto solo — nessun braccio di ferro di specificità.

§3.2Diagrammi Mermaid

Un blocco ```mermaid lascia al momento della build solo un segnaposto; il renderer si carica dinamicamente solo sulle pagine che portano un diagramma (le pagine senza non pagano nulla) e ridisegna quando il tema cambia:

flowchart LR
  A["astro-inkbrush<br/>motore: editing / dialetto / guardiano"] --> C["il tuo sito<br/>identità / rotte / deployment"]
  B["astro-inkstone<br/>carta: token / stili / pipeline"] --> C
  A -. un solo dialetto condiviso .-> B

§3.3Gli extra di GFM

Gli elenchi di attività e le note a piè di pagina viaggiano con GFM:

• token importati
• base.css importato
• tavolozza d’identità sovrascritta

Un’affermazione che merita una fonte riceve una nota a piè di pagina.¹

§4.1Che cosa respinge il guardiano su questa pagina

Che questa pagina compili è di per sé la dimostrazione che tutto quanto sopra è ben formato. Queste grafie farebbero fallire la build sul posto (provane una, poi npm run build):

• un segno di enfasi che non può accoppiarsi, come un ** lasciato aperto a fine riga;
• $$x$$ su riga singola (usa la forma su tre righe);
• titoli numerati a mano — scrivere il titolo di questa sezione come ## 9. Che cosa respinge… colliderebbe con la numerazione a tempo di build e verrebbe segnalato;
• MDX che valuta le graffe del tuo discorso: {0,1,2,3} renderebbe come un semplice 3, quindi il guardiano esige la forma protetta {0,1,2,3};
• una formula che KaTeX non sa rendere (il guardiano ri-rende ogni formula in modalità strict invece di lasciar salpare testo rosso d’errore).