f5xc-docs-tools

O plugin f5xc-docs-tools valida arquivos de conteúdo MDX para o pipeline de documentação f5-sales-demo. Ele detecta problemas comuns que quebram a compilação antes que cheguem ao CI, incluindo caracteres JSX expostos, importações inválidas, referências de imagem quebradas e frontmatter incompleto.

v1.1.2 Produtividade

Instalação

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

Habilidades

mdx-content-reviewer

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

Validação de frontmatter

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

Armadilhas de sintaxe MDX

Detecta caracteres < expostos e chaves \{ \} não escapadas que quebram a análise do MDX.

Validação de importações

Valida importações em relação a uma lista de permissões dos componentes integrados do Starlight e do tema f5-sales-demo.

Atributos de componentes

Verifica as props obrigatórias de 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 existe e que os diretórios de imagens não contêm arquivos MDX indevidos.

Exportações e blocos de código

Verifica se as variáveis usadas nas props code do componente Code possuem exportações correspondentes.

Comportamento de escopo

A habilidade aplica o escopo de revisão de forma inteligente:

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

Formato de saída

Os resultados são agrupados por severidade:

• ERROR — quebrará a compilação; deve ser corrigido antes de mesclar
• WARNING — problemas prováveis que devem ser tratados
• INFO — sugestões e boas práticas

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

Comandos

/review-mdx

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

Executa a habilidade mdx-content-reviewer sob demanda.

Argumentos:

Argumento	Obrigatório	Descrição
path-or-glob	Não	Caminho de arquivo ou padrão glob para delimitar a revisão. O padrão sã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 a contagem de resultados por severidade.

Importações Permitidas

O plugin valida importações em relação a 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

Os componentes do tema utilizam importações padrão de arquivos .astro individuais. Importações diretas de node_modules, caminhos relativos e chamadas require() são sinalizadas 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 detecta:

Armadilha	Problema	Correção
< exposto	MDX interpreta como tag JSX	Use <, código inline ou reformule
\{ \} não escapadas	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