f5xc-docs-tools

El plugin f5xc-docs-tools valida archivos de contenido MDX para el pipeline de documentación de f5-sales-demo. Detecta problemas comunes que rompen la compilación antes de que lleguen a CI, incluyendo caracteres JSX sin escapar, importaciones inválidas, referencias de imágenes rotas y frontmatter incompleto.

v1.1.2 Productividad

Instalación

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

Habilidades

mdx-content-reviewer

Esta habilidad se activa automáticamente cuando Claude detecta que está trabajando con archivos MDX en un repositorio de contenido de f5-sales-demo. Realiza siete comprobaciones de validación:

Validación de frontmatter

Comprueba campos requeridos como title y sidebar.order. Las páginas splash deben incluir campos hero y template: splash.

Errores comunes de sintaxis MDX

Detecta caracteres < sin escapar y llaves \{ \} sin escapar que rompen el análisis MDX.

Validación de importaciones

Valida las importaciones contra una lista permitida de componentes integrados de Starlight y componentes del tema f5-sales-demo.

Atributos de componentes

Comprueba las props requeridas para componentes como Screenshot, Aside, Code, LinkCard, Card y Badge.

Referencias de imágenes

Verifica que las imágenes referenciadas existan en el directorio docs/images/.

Comprobaciones de estructura

Asegura que docs/index.mdx exista y que los directorios de imágenes no contengan archivos MDX sueltos.

Exportaciones y bloques de código

Verifica que las variables utilizadas en las props code del componente Code tengan exportaciones correspondientes.

Comportamiento de alcance

La habilidad determina de forma inteligente su alcance de revisión:

Si hay cambios no confirmados o en staging en archivos docs/**/*.mdx, solo se revisan esos archivos
De lo contrario, se revisan todos los archivos docs/**/*.mdx

Formato de salida

Los hallazgos se agrupan por severidad:

ERROR — romperá la compilación; debe corregirse antes de hacer merge
WARNING — problemas probables que deben abordarse
INFO — sugerencias y mejores prácticas

Cada hallazgo incluye la ruta del archivo, el número de línea y una descripción del problema.

Comandos

/review-mdx

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

Ejecuta la habilidad mdx-content-reviewer bajo demanda.

Argumentos:

Argumento	Requerido	Descripción
`path-or-glob`	No	Ruta de archivo o patrón glob para delimitar el alcance de la revisión. Por defecto revisa todos los archivos `docs/*/.mdx`.

Ejemplos:

# Revisar todos los archivos MDX en docs/
/f5xc-docs-tools:review-mdx

# Revisar un archivo específico
/f5xc-docs-tools:review-mdx docs/getting-started.mdx

# Revisar archivos que coincidan con un glob
/f5xc-docs-tools:review-mdx docs/guides/*.mdx

Salida: Una línea de resumen al final reporta el total de archivos revisados y el conteo de hallazgos por severidad.

Importaciones permitidas

El plugin valida las importaciones contra estas fuentes:

Componentes integrados de Starlight (@astrojs/starlight/components):

Aside Badge Card CardGrid Code FileTree Icon LinkCard Steps TabItem Tabs

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

Banner Icon LinkCard Screenshot

Referencia rápida de componentes

Componente	Props requeridas	Props opcionales
Screenshot	`alt` + al menos una de `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	—	—

Errores comunes de MDX

Problemas comunes que el plugin detecta:

Error	Problema	Solución
`<` sin escapar	MDX lo interpreta como etiqueta JSX	Use `&lt;`, código en línea o reformule
`\{` `\}` sin escapar	MDX lo trata como expresión JSX	Use código en línea, escape con `\` o use un bloque de código
Llaves en nombres de archivo	Astro no puede procesar el archivo	Nunca use `\{` o `\}` en nombres de archivos `.mdx`