f5xc-docs-tools

f5xc-docs-tools 插件用于验证 f5-sales-demo 文档管道中的 MDX 内容文件。它能在构建问题进入 CI 之前提前捕获常见的构建中断问题，包括裸露的 JSX 字符、无效的导入、损坏的图片引用以及不完整的 frontmatter。

v1.1.2 生产力

安装

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

技能

mdx-content-reviewer

当 Claude 检测到您正在 f5-sales-demo 内容仓库中处理 MDX 文件时，此技能将自动激活。它执行七项验证检查：

Frontmatter 验证

检查 title 和 sidebar.order 等必填字段。 Splash 页面必须包含 hero 字段和 template: splash。

MDX 语法陷阱

检测会导致 MDX 解析失败的裸露 < 字符和未转义的 \{ \} 大括号。

导入验证

根据 Starlight 内置组件和 f5-sales-demo 主题组件的允许列表验证导入。

组件属性

检查 Screenshot、Aside、Code、LinkCard、Card 和 Badge 等组件的必填属性。

图片引用

验证所引用的图片是否存在于 docs/images/ 目录中。

结构检查

确保 docs/index.mdx 存在，且图片目录中不包含多余的 MDX 文件。

导出与代码块

验证 Code 组件 code 属性中使用的变量是否具有对应的导出声明。

扫描范围行为

该技能会智能地确定审查范围：

如果 docs/**/*.mdx 文件存在未提交或已暂存的更改，则仅审查这些文件
否则，审查所有 docs/**/*.mdx 文件

输出格式

检查结果按严重程度分组：

ERROR（错误）— 将导致构建失败；合并前必须修复
WARNING（警告）— 应当处理的潜在问题
INFO（信息）— 建议与最佳实践

每条结果均包含文件路径、行号以及问题描述。

命令

/review-mdx

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

按需运行 mdx-content-reviewer 技能。

参数：

参数	是否必填	描述
`path-or-glob`	否	用于限定审查范围的文件路径或 glob 模式。默认为所有 `docs/*/.mdx` 文件。

示例：

# 审查 docs/ 中的所有 MDX 文件
/f5xc-docs-tools:review-mdx

# 审查特定文件
/f5xc-docs-tools:review-mdx docs/getting-started.mdx

# 审查符合 glob 模式的文件
/f5xc-docs-tools:review-mdx docs/guides/*.mdx

输出： 末尾的摘要行报告已审查的文件总数以及各严重程度的问题数量。

允许的导入

插件根据以下来源验证导入：

Starlight 内置组件 (@astrojs/starlight/components)：

Aside Badge Card CardGrid Code FileTree Icon LinkCard Steps TabItem Tabs

f5-sales-demo 主题组件 (@f5-sales-demo/docs-theme/components/)：

Banner Icon LinkCard Screenshot

组件快速参考

组件	必填属性	可选属性
Screenshot	`alt` + `light` 或 `dark` 中至少一个	—
Aside	`type`	`title`
Code	`code`、`lang`	`title`、`frame`、`mark`、`ins`、`del`
LinkCard（主题）	`title`、`href`	`description`、`icon`
Card	`title`	`icon`
Badge	`text`	`variant`
Steps	—	—
Tabs / TabItem	TabItem：`label`	—
CardGrid	—	—
FileTree	—	—

MDX 常见陷阱

插件捕获的常见问题：

陷阱	问题描述	修复方案
裸露的 `<`	MDX 将其解析为 JSX 标签	使用 `&lt;`、行内代码或改写表述
未转义的 `\{` `\}`	MDX 将其视为 JSX 表达式	使用行内代码、用 `\` 转义或改用代码块
文件名中含大括号	Astro 无法处理该文件	切勿在 `.mdx` 文件名中使用 `\{` 或 `\}`