f5xc-docs-tools

Il plugin f5xc-docs-tools valida i file di contenuto MDX per la pipeline di documentazione f5-sales-demo. Intercetta i problemi comuni che interrompono la build prima che raggiungano la CI, inclusi caratteri JSX non protetti, import non validi, riferimenti a immagini non funzionanti e frontmatter incompleti.

v1.1.2 Produttività

Installazione

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

Competenze

mdx-content-reviewer

Questa competenza 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

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

Insidie della sintassi MDX

Rileva i caratteri < non protetti e le parentesi graffe \{ \} non escapate che interrompono il parsing MDX.

Validazione degli import

Valida gli import rispetto a una lista consentita di componenti integrati di Starlight e del tema f5-sales-demo.

Attributi dei componenti

Controlla 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 scoping

La competenza definisce in modo intelligente l’ambito della revisione:

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

Formato dell’output

I risultati sono raggruppati per gravità:

ERRORE — interromperà la build; da correggere prima del merge
AVVERTIMENTO — problemi probabili che dovrebbero essere risolti
INFO — suggerimenti e buone pratiche

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 competenza mdx-content-reviewer su richiesta.

Argomenti:

Argomento	Obbligatorio	Descrizione
`path-or-glob`	No	Percorso del file o pattern glob per definire l’ambito della revisione. Per impostazione predefinita 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 glob
/f5xc-docs-tools:review-mdx docs/guides/*.mdx

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

Import consentiti

Il plugin valida gli import rispetto a queste fonti:

Componenti integrati di Starlight (@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	—	—

Insidie MDX

Problemi comuni intercettati dal plugin:

Insidia	Problema	Soluzione
`<` non protetto	MDX lo interpreta come tag JSX	Utilizzare `&lt;`, codice inline o riformulare
`\{` `\}` non escapate	MDX le tratta come espressioni JSX	Utilizzare codice inline, escapare con `\` o usare un blocco di codice
Parentesi graffe nei nomi file	Astro non riesce a elaborare il file	Non usare mai `\{` o `\}` nei nomi file `.mdx`