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。启动页面必须包含 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` 文件名中使用 `\{` 或 `\}`