f5xc-docs-tools

Il plugin f5xc-docs-tools valida i file di contenuto MDX per la pipeline di documentazione f5-sales-demo. Individua i problemi comuni che interrompono la build prima che raggiungano la CI, tra cui caratteri JSX esposti, importazioni non valide, riferimenti a immagini non funzionanti e frontmatter incompleto.

v1.1.2 Produttività

Installazione

/plugin install f5xc-docs-tools@f5-sales-demo-marketplace

Funzionalità

mdx-content-reviewer

Questa funzionalità si attiva automaticamente quando Claude rileva che si sta lavorando con file MDX in un repository di contenuti f5-sales-demo. Esegue sette controlli di validazione:

Validazione del frontmatter

Verifica i campi obbligatori come title e sidebar.order. Le pagine splash devono includere i campi hero e template: splash.

Problematiche della sintassi MDX

Rileva caratteri < esposti e parentesi graffe \{ \} non precedute da escape che interrompono l’analisi MDX.

Validazione delle importazioni

Convalida le importazioni rispetto a un elenco di componenti Starlight integrati e del tema f5-sales-demo.

Attributi dei componenti

Verifica le props obbligatorie per componenti come Screenshot, Aside, Code, LinkCard, Card e Badge.

Riferimenti alle immagini

Verifica che le immagini referenziate esistano nella directory docs/images/.

Controlli strutturali

Assicura che docs/index.mdx esista e che le directory delle immagini non contengano file MDX estranei.

Export e blocchi di codice

Verifica che le variabili utilizzate nelle props code del componente Code abbiano export corrispondenti.

Comportamento di delimitazione dell’ambito

La funzionalità delimita in modo intelligente l’ambito della revisione:

Se sono presenti modifiche non committate o in staging nei file docs/**/*.mdx, vengono revisionati solo quei file
Altrimenti, vengono revisionati tutti i file docs/**/*.mdx

Formato di output

I risultati sono raggruppati per gravità:

ERROR — interromperà la build; da correggere prima del merge
WARNING — problemi probabili che dovrebbero essere affrontati
INFO — suggerimenti e best practice

Ogni risultato include il percorso del file, il numero di riga e una descrizione del problema.

Comandi

/review-mdx

/f5xc-docs-tools:review-mdx [path-or-glob]

Esegue la funzionalità mdx-content-reviewer su richiesta.

Argomenti:

Argomento	Obbligatorio	Descrizione
`path-or-glob`	No	Percorso del file o pattern glob per delimitare l’ambito della revisione. Il valore predefinito include tutti i file `docs/*/.mdx`.

Esempi:

# Revisiona tutti i file MDX in docs/
/f5xc-docs-tools:review-mdx

# Revisiona un file specifico
/f5xc-docs-tools:review-mdx docs/getting-started.mdx

# Revisiona i file corrispondenti a un pattern glob
/f5xc-docs-tools:review-mdx docs/guides/*.mdx

Output: Una riga di riepilogo alla fine riporta il numero totale di file revisionati e il conteggio dei risultati per gravità.

Importazioni consentite

Il plugin convalida le importazioni rispetto a queste sorgenti:

Componenti Starlight integrati (@astrojs/starlight/components):

Aside Badge Card CardGrid Code FileTree Icon LinkCard Steps TabItem Tabs

Componenti del tema f5-sales-demo (@f5-sales-demo/docs-theme/components/):

Banner Icon LinkCard Screenshot

Riferimento rapido dei componenti

Componente	Props obbligatorie	Props opzionali
Screenshot	`alt` + almeno uno tra `light` o `dark`	—
Aside	`type`	`title`
Code	`code`, `lang`	`title`, `frame`, `mark`, `ins`, `del`
LinkCard (tema)	`title`, `href`	`description`, `icon`
Card	`title`	`icon`
Badge	`text`	`variant`
Steps	—	—
Tabs / TabItem	TabItem: `label`	—
CardGrid	—	—
FileTree	—	—

Problematiche MDX

Problemi comuni che il plugin individua:

Problematica	Problema	Soluzione
`<` esposto	MDX interpreta come tag JSX	Usare `&lt;`, codice inline o riformulare
`\{` `\}` senza escape	MDX tratta come espressione JSX	Usare codice inline, aggiungere escape con `\`, o usare un blocco di codice
Parentesi graffe nei nomi di file	Astro non riesce a elaborare il file	Non usare mai `\{` o `\}` nei nomi di file `.mdx`