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 susceptibles de bloquer la compilation avant qu’ils n’atteignent l’intégration continue, notamment les caractères JSX bruts, les imports invalides, les références d’images incorrectes et les métadonnées frontmatter incomplètes.

v1.1.2 Productivity

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 tels que title et sidebar.order. Les pages de présentation doivent inclure les champs hero et template: splash.

Pièges de syntaxe MDX

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

Validation des imports

Valide les imports par rapport à une liste d’autorisation des composants intégrés Starlight et des Composants du thème f5-sales-demo.

Attributs des composants

Vérifie les props obligatoires pour les composants tels que 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 aucun fichier MDX parasite.

Exports et blocs de code

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

Comportement de périmètre

La compétence délimite intelligemment son périmètre d’analyse :

• Si des modifications non validées ou en attente de commit concernent des fichiers docs/**/*.mdx, seuls ces fichiers sont examinés
• Dans le cas contraire, tous les fichiers docs/**/*.mdx sont examinés

Format de sortie

Les résultats sont regroupés par niveau de sévérité :

• ERROR — bloquera la compilation ; doit être corrigé avant la fusion
• 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 l’analyse. Par défaut, tous les fichiers docs/**/*.mdx.

Exemples :

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

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

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

Sortie : Une ligne récapitulative à la fin indique le nombre total de fichiers analysés et le nombre de résultats par niveau de sévérité.

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

Attention

Les composants du thème utilisent des imports par défaut depuis des fichiers .astro individuels. Les imports directs depuis node_modules, les chemins relatifs et les appels require() sont signalés comme avertissements.

Référence rapide des composants

Composant	Props obligatoires	Props optionnelles
Screenshot	alt + au moins 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
< brut	MDX l’interprète comme une balise JSX	Utiliser <, du code inline ou reformuler
\{ \} non échappées	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