f5xc-docs-tools

O plugin f5xc-docs-tools valida arquivos de conteúdo MDX para o pipeline de documentação f5-sales-demo. Ele captura problemas comuns que quebram o build antes que cheguem ao CI, incluindo caracteres JSX soltos, imports inválidos, referências de imagem quebradas e frontmatter incompleto.

v1.1.2 Produtividade

Instalação

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

Skills

mdx-content-reviewer

Esta skill é ativada automaticamente quando o Claude detecta que você está trabalhando com arquivos MDX em um repositório de conteúdo f5-sales-demo. Ela executa sete verificações de validação:

Validação de frontmatter

Verifica campos obrigatórios como title e sidebar.order. Páginas splash devem incluir campos hero e template: splash.

Armadilhas de sintaxe MDX

Detecta caracteres < soltos e chaves \{ \} sem escape que quebram a análise do MDX.

Validação de imports

Valida imports contra uma lista permitida de componentes integrados do Starlight e componentes do tema f5-sales-demo.

Atributos de componentes

Verifica props obrigatórias para componentes como Screenshot, Aside, Code, LinkCard, Card e Badge.

Referências de imagens

Verifica se as imagens referenciadas existem no diretório docs/images/.

Verificações de estrutura

Garante que docs/index.mdx exista e que diretórios de imagens não contenham arquivos MDX dispersos.

Exports e blocos de código

Verifica se variáveis usadas nas props code do componente Code possuem exports correspondentes.

Comportamento de escopo

A skill define o escopo da revisão de forma inteligente:

• Se houver alterações não commitadas ou staged em arquivos docs/**/*.mdx, apenas esses arquivos são revisados
• Caso contrário, todos os arquivos docs/**/*.mdx são revisados

Formato de saída

Os achados são agrupados por severidade:

• ERROR — irá quebrar o build; deve ser corrigido antes do merge
• WARNING — problemas prováveis que devem ser tratados
• INFO — sugestões e boas práticas

Cada achado inclui o caminho do arquivo, número da linha e uma descrição do problema.

Comandos

/review-mdx

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

Executa a skill mdx-content-reviewer sob demanda.

Argumentos:

Argumento	Obrigatório	Descrição
path-or-glob	Não	Caminho de arquivo ou padrão glob para definir o escopo da revisão. O padrão é todos os arquivos docs/**/*.mdx.

Exemplos:

# Revisar todos os arquivos MDX em docs/
/f5xc-docs-tools:review-mdx

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

# Revisar arquivos que correspondem a um glob
/f5xc-docs-tools:review-mdx docs/guides/*.mdx

Saída: Uma linha de resumo ao final reporta o total de arquivos revisados e contagens de achados por severidade.

Imports Permitidos

O plugin valida imports contra estas fontes:

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

Aside Badge Card CardGrid Code FileTree Icon LinkCard Steps TabItem Tabs

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

Banner Icon LinkCard Screenshot

Cuidado

Componentes do tema usam imports padrão (default) de arquivos .astro individuais. Imports diretos de node_modules, caminhos relativos e chamadas require() são sinalizados como avisos.

Referência Rápida de Componentes

Componente	Props Obrigatórias	Props Opcionais
Screenshot	alt + pelo menos um entre light ou 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	—	—

Armadilhas do MDX

Problemas comuns que o plugin captura:

Armadilha	Problema	Correção
< solto	MDX interpreta como tag JSX	Use <, código inline ou reformule
\{ \} sem escape	MDX trata como expressão JSX	Use código inline, escape com \ ou use bloco de código
Chaves em nomes de arquivos	Astro não consegue processar o arquivo	Nunca use \{ ou \} em nomes de arquivos .mdx