f5xc-docs-tools

Le plugin f5xc-docs-tools valide les fichiers de contenu MDX pour le pipeline de documentation f5-sales-demo. Il détecte les problèmes courants qui cassent le build avant qu’ils n’atteignent le CI, notamment les caractères JSX non échappés, les imports invalides, les références d’images cassées et les frontmatter incomplets.

v1.1.2 Productivité

Installation

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

Compétences

mdx-content-reviewer

Cette compétence s’active automatiquement lorsque Claude détecte que vous travaillez avec des fichiers MDX dans un dépôt de contenu f5-sales-demo. Elle effectue sept contrôles de validation :

Validation du frontmatter

Vérifie les champs obligatoires comme title et sidebar.order. Les pages splash doivent inclure les champs hero et template: splash.

Pièges de syntaxe MDX

Détecte les caractères < non échappés et les accolades \{ \} non échappées qui cassent l’analyse MDX.

Validation des imports

Valide les imports par rapport à une liste autorisée de composants intégrés Starlight et de composants du thème f5-sales-demo.

Attributs des composants

Vérifie les props obligatoires pour les composants comme Screenshot, Aside, Code, LinkCard, Card et Badge.

Références d'images

Vérifie que les images référencées existent dans le répertoire docs/images/.

Contrôles de structure

S’assure que docs/index.mdx existe et que les répertoires d’images ne contiennent pas de fichiers MDX égarés.

Exports et blocs de code

Vérifie que les variables utilisées dans les props code du composant Code ont des exports correspondants.

Comportement de portée

La compétence délimite intelligemment sa revue :

S’il y a des modifications non committées ou indexées dans les fichiers docs/**/*.mdx, seuls ces fichiers sont examinés
Sinon, tous les fichiers docs/**/*.mdx sont examinés

Format de sortie

Les résultats sont regroupés par gravité :

ERROR — cassera le build ; à corriger impérativement avant le merge
WARNING — problèmes probables qui devraient être traités
INFO — suggestions et bonnes pratiques

Chaque résultat inclut le chemin du fichier, le numéro de ligne et une description du problème.

Commandes

/review-mdx

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

Exécute la compétence mdx-content-reviewer à la demande.

Arguments :

Argument	Obligatoire	Description
`path-or-glob`	Non	Chemin de fichier ou motif glob pour délimiter la revue. Par défaut, tous les fichiers `docs/*/.mdx`.

Exemples :

# Examiner tous les fichiers MDX dans docs/
/f5xc-docs-tools:review-mdx

# Examiner un fichier spécifique
/f5xc-docs-tools:review-mdx docs/getting-started.mdx

# Examiner les fichiers correspondant à un glob
/f5xc-docs-tools:review-mdx docs/guides/*.mdx

Sortie : Une ligne de résumé à la fin indique le nombre total de fichiers examinés et le nombre de résultats par gravité.

Imports autorisés

Le plugin valide les imports par rapport à ces sources :

Composants intégrés Starlight (@astrojs/starlight/components) :

Aside Badge Card CardGrid Code FileTree Icon LinkCard Steps TabItem Tabs

Composants du thème f5-sales-demo (@f5-sales-demo/docs-theme/components/) :

Banner Icon LinkCard Screenshot

Référence rapide des composants

Composant	Props obligatoires	Props optionnelles
Screenshot	`alt` + au moins un parmi `light` ou `dark`	—
Aside	`type`	`title`
Code	`code`, `lang`	`title`, `frame`, `mark`, `ins`, `del`
LinkCard (thème)	`title`, `href`	`description`, `icon`
Card	`title`	`icon`
Badge	`text`	`variant`
Steps	—	—
Tabs / TabItem	TabItem : `label`	—
CardGrid	—	—
FileTree	—	—

Pièges MDX

Problèmes courants détectés par le plugin :

Piège	Problème	Correction
`<` non échappé	MDX l’interprète comme une balise JSX	Utiliser `&lt;`, du code inline ou reformuler
`\{` `\}` non échappés	MDX les traite comme une expression JSX	Utiliser du code inline, échapper avec `\` ou utiliser un bloc de code
Accolades dans les noms de fichiers	Astro ne peut pas traiter le fichier	Ne jamais utiliser `\{` ou `\}` dans les noms de fichiers `.mdx`