Passa al contenuto principale

Gestire Link Cross-Sito

Quando il tuo progetto ospita più di un'istanza Docusaurus sotto lo stesso dominio (per esempio un'area Utente in /docs/ e un'area Developer in /developers/), i link che attraversano i confini delle istanze devono usare URL link (root-relative /developers/… o URL completo) invece di path file Markdown relativi. Docusaurus non risolve i path file relativi attraverso i confini dei plugin — e nemmeno il validator dei link di Zenzic.

Per impostazione predefinita, la regola Z105 ABSOLUTE_PATH di Zenzic rifiuta qualsiasi link assoluto (/foo/bar) perché i path assoluti si rompono quando il sito è ospitato in una sottocartella. Questa guida mostra come dichiarare i prefissi cross-istanza che il tuo progetto possiede legittimamente, in modo che il validator smetta di segnalarli — senza indebolire Z105 altrove.

TL;DR — Quale strumento, quando?​

SituazioneUsa questoNon usare
Una singola riga isolata in un file matcha legittimamente una regola<!-- zenzic:ignore: Zxxx --> (oppure {/* zenzic:ignore: Zxxx */} per MDX)—
Più link cross-plugin in file diversiIgnore inline — uno per link—

La regola decisionale: se è una proprietà di una riga, va inline.

Gestione dei Prefissi Cross-Istanza​

[link_validation] rimosso

Lo schema TOML [link_validation] — incluso absolute_path_allowlist — non è supportato e genera un errore di validazione TOML all'avvio. Un .zenzic.toml che dichiara ancora [link_validation] va aggiornato.

Per i link cross-istanza segnalati da Z105, usa gli ignore inline su ogni riga interessata.

Quando usare un ignore inline​

Gli ignore inline sono chirurgici. Usali quando:

  • Una singola riga in un singolo file innesca legittimamente una regola (es. un esempio di documentazione che sembra una credenziale ma è fittizio).
  • L'eccezione è contesto locale, non una verità di progetto.
<!-- zenzic:ignore: Z201 -->
api_key = "sk_test_PLACEHOLDER_FOR_DOCS"
{/* zenzic:ignore: Z105 */}
[Esempio di link hard](/legacy/path)

La forma inline lascia un audit trail nella riga esatta — visibile nei diff delle PR, tracciabile con git blame.

Anti-pattern: abuso degli ignore inline​

Non aggiungere <!-- zenzic:ignore: Z1XX --> come soppressione generale. Questo:

  • Implica che il link sia "rotto e accettato" mentre in realtà è corretto per design.
  • Nasconde la dipendenza cross-istanza ai revisori della PR.

Annota gli ignore inline con un commento che spieghi perché il link è legittimamente assoluto, così la soppressione è tracciabile con git blame.

Tornare indietro​

Rimuovi un ignore inline e l'enforcement di Z105 ritorna immediatamente su quella riga. Non c'è costo di migrazione.

Gestire l'Identità Virtuale: Route basate sullo Slug​

Docusaurus permette a qualsiasi pagina di dichiarare uno slug: personalizzato nel frontmatter che sovrascrive completamente l'URL derivato dal nome del file. Una volta dichiarato, solo l'URL dello slug esiste nella tabella di routing di Docusaurus — il percorso del filename originale non esiste più.

Zenzic applica questa identità al momento della validazione. Quando l'adapter Docusaurus è attivo, set_slug_map() legge gli slug dal frontmatter prima di costruire la Virtual Site Map (VSM). La VSM contiene quindi solo l'URL canonico dello slug — non l'URL derivato dal nome del file.

Identificare la route corretta​

Data una pagina con il seguente frontmatter:

---
slug: sample-post
title: Un Post di Esempio
---
LinkRisultato
[Post](/blog/2026-05-05-post)❌ Z104 — path derivato dal filename assente dalla VSM
[Post](/blog/sample-post)✅ Validato — lo slug corrisponde alla voce nella VSM

Il validator solleva Z104 FILE_NOT_FOUND (non Z105) perché /blog/ è un prefisso di proprietà del progetto. Il prefisso è fidato; la route esatta deve comunque esistere.

Trovare lo slug canonico​

Esegui zenzic inspect routes --kind physical per elencare ogni route nella VSM insieme al file sorgente e allo slug nel frontmatter:

$ zenzic inspect routes --kind physical
/blog/sample-post/   ←  blog/2026-05-05-post.md  [slug: sample-post]

Aggiorna qualsiasi link che punta al percorso derivato dal filename con l'URL dello slug mostrato nell'output.

Agnosticità dal motore​

La risoluzione della slug-map è selettiva per adapter. Gli adapter più semplici (Standalone, MkDocs) non sono influenzati — il percorso slug-map è una capacità esclusiva di Docusaurus. Non è necessaria alcuna modifica di configurazione quando si cambia adapter.

Correlati​