BxSites Content-Quality Checks 是 bx-sites(ortus-boxlang/bx-sites)项目提供的面向作者的内容质量检查工具,作用于原始 docs/ 目录下的 Markdown 源文件,可在完整构建之前或替代完整构建运行。每个命令均以 bxSites <verb> [options](或 boxlang bxSites <verb> [options])形式执行,并接受 --projectRoot=<path> 指定项目根目录。
用途
该技能用于在正式构建前对内容做质量预检,包括结构检查、博客日期检查、草稿露出、博客筛选以及搜索索引查询,帮助作者在不打开浏览器的情况下提前发现问题。
主要能力
lint:构建前的内容质量检查,针对原始 docs/ Markdown,与只检查已构建 site/ 的 audit(见 bx-sites-build)不同。检查两项:一是标题层级跳级,即页面正文从 ## 直接跳到 #### 而中间没有 ###,这种结构容易造成困惑且不利于无障碍访问;fenced 代码块内的行不会被误判为标题。二是博客文章日期问题,即 docs/blog/posts/** 下的文章 frontmatter 中日期缺失或无效(真实构建在加载文章时会直接抛错,lint 则先把它作为一项发现暴露出来)。任一检查发现问题时退出码为 1,否则为 0。
blog:drafts:列出所有 frontmatter 中设置 draft: true 的博客文章。真实构建总会跳过草稿,因此这是唯一能看到草稿存在的地方。始终退出码 0。
blog:find:无需完整构建即可按作者、分类、标签、日期范围筛选博客文章。命令为 bxSites blog:find [--author=] [--category=] [--tag=] [--since=] [--until=] [--drafts]。其中 --author、--category、--tag 对文章自身对应值做大小写不敏感的精确匹配;--since、--until 为日期,仅匹配在 --since 当日或之后、和/或在 --until 当日或之前的文章;--drafts 表示同时包含草稿(默认排除)。所有筛选条件都是可选且相互独立的,不传任何条件时列出全部已发布文章。文章 frontmatter 相关内容可参见 bx-sites-blog-versioning-i18n。
search:query:对已构建的 site/search-index.json 执行关键词查询,需先运行 bxSites build 或 bxSites search-index(见 bx-sites-build)。命令为 bxSites search:query --query="getting started" [--limit=10]。--query 为必填,是空格分隔的搜索词;--limit 为返回结果上限,默认 10。结果排序使用与客户端搜索组件相同的字段相对权重(标题、标签、标题层级、正文),因此项目无需打开浏览器即可校验真实访客搜索会呈现什么结果。底层 provider 参见 bx-sites-search;该 verb 只读取主 docs/ 树的本地索引,不读取版本/语言树自己的索引,并且在 algolia/pagefind provider 下为空操作(这两者都不使用本地 search-index.json)。
使用方式
典型发布前内容检查流程为:先运行 bxSites lint,再运行 bxSites blog:drafts 确认没有本应发布的内容仍处于草稿状态,然后运行 bxSites build,最后运行 bxSites audit 检查失效链接与 alt 文本(详见 bx-sites-build)。
适用场景
适用于 bx-sites 项目的作者在提交或发布前检查内容质量、提前发现标题结构与博客日期问题、确认草稿状态、按条件筛选博客文章,以及在不打开浏览器的情况下校验本地搜索索引的返回结果。
限制
search:query 依赖于已构建的 search-index.json,且在 algolia/pagefind provider 下不生效;它只读取主 docs/ 树索引。lint 与 audit 的检查范围不同:lint 面向原始 Markdown,audit 面向已构建的 site/。资料未提供该技能的收费、价格、平台支持范围或性能效果等信息。