脚本工具使用指南

简述

本站提供了多个强大的脚本工具来帮助维护和管理文档内容。这些工具可以自动化许多重复性任务，提高文档维护效率。

所有脚本都位于 .vitepress/scripts/ 目录下，并已集成到 package.json 中，可以通过 npm 命令直接使用。

可用脚本概览

脚本名称	命令	用途	状态
Frontmatter 编辑器	`npm run update-frontmatter`	批量更新 markdown 文件的 frontmatter	✅ 可用
标题同步器	`npm run update-titles`	同步 index.md 标题到 locales.json	✅ 可用
侧边栏构建器	`npm run docs:build`	构建侧边栏配置	✅ 自动集成
Index.md 生成器	`npm run create-indexes`	为缺少 index.md 的文件夹创建索引文件	✅ 可用

Frontmatter 编辑器

功能描述

Frontmatter 编辑器是最强大的脚本工具，可以批量更新 markdown 文件的 frontmatter 字段。支持递归处理文件夹及其子文件夹中的所有 markdown 文件。

支持的字段

字段名	类型	描述	示例
`title`	string	文章标题	`"环境配置指南"`
`editor`	string	编辑者名称	`"张三"`
`authors`	string[]	作者列表	`["李四", "王五"]`
`description`	string	文章描述	`"本文介绍如何配置开发环境"`
`progress`	number	编写进度 (0-100)	`85`
`state`	string	文章状态	`"published"` / `"draft"` / `"outdated"`
`outline`	number[] \| boolean	大纲层级	`[2, 3]` / `false`
`showComment`	boolean	显示评论区	`true` / `false`
`gitChangelog`	boolean	显示 Git 变更日志	`true` / `false`
`noguide`	boolean	是否在侧边栏显示	`true` / `false`
`backPath`	string	返回按钮路径	`"../"`
`layout`	string	页面布局	`"doc"` / `"home"`
`tags`	string[]	文章标签	`["教程", "配置"]`

基本用法

更新单个字段

bash

# 为 docs/zh 目录下所有 md 文件设置编辑者
npm run update-frontmatter -- -p docs/zh -e "张三"

# 为 docs/zh/guide 目录设置作者
npm run update-frontmatter -- -p docs/zh/guide -a "李四,王五"

# 设置文章标题
npm run update-frontmatter -- -p docs/zh/api --title "API 参考文档"

更新多个字段

bash

# 同时设置多个字段
npm run update-frontmatter -- -p docs/zh/tutorial \
  --title "教程文档" \
  --editor "张三" \
  --authors "李四,王五" \
  --description "完整的教程文档" \
  --progress 90 \
  --state published

安全操作选项

bash

# 预览更改（不实际修改文件）
npm run update-frontmatter -- -p docs/zh/guide -e "张三" --dry-run

# 创建备份文件
npm run update-frontmatter -- -p docs/zh/guide -e "张三" --backup

# 显示详细信息
npm run update-frontmatter -- -p docs/zh/guide -e "张三" --verbose

# 强制覆盖现有值
npm run update-frontmatter -- -p docs/zh/guide -e "新编辑者" --force

高级功能

文件过滤

bash

# 排除特定文件夹
npm run update-frontmatter -- -p docs -e "张三" --exclude "**/temp/**" --exclude "**/draft/**"

# 只处理特定模式的文件
npm run update-frontmatter -- -p docs --include "**/*guide*.md" -e "张三"

作者管理操作

bash

# 添加新作者到现有列表
npm run update-frontmatter -- -p docs/zh/guide --add-author "新作者"

# 移除特定作者
npm run update-frontmatter -- -p docs/zh/guide --remove-author "旧作者"

# 替换作者名称
npm run update-frontmatter -- -p docs/zh/guide --replace-author "旧名称,新名称"

# 组合操作：先移除旧作者，再添加新作者
npm run update-frontmatter -- -p docs/zh/guide --remove-author "作者A" --add-author "作者B"

批量状态管理

bash

# 将所有草稿标记为已发布
npm run update-frontmatter -- -p docs/zh --state "published" --dry-run

# 批量设置进度
npm run update-frontmatter -- -p docs/zh/completed --progress 100

完整参数列表

参数	简写	描述	示例
`--path`	`-p`	目标文件夹路径（必需）	`-p docs/zh`
`--title`	`-t`	设置标题	`-t "我的文档"`
`--editor`	`-e`	设置编辑者	`-e "张三"`
`--authors`	`-a`	设置作者（逗号分隔，替换全部）	`-a "李四,王五"`
`--add-author`		添加新作者到现有列表	`--add-author "张三"`
`--remove-author`		从列表中移除作者	`--remove-author "李四"`
`--replace-author`		替换指定作者	`--replace-author "旧名,新名"`
`--description`	`-d`	设置描述	`-d "文档描述"`
`--progress`		设置进度	`--progress 85`
`--state`		设置状态	`--state published`
`--outline`		设置大纲	`--outline "2,3"`
`--no-comment`		禁用评论	`--no-comment`
`--no-changelog`		禁用变更日志	`--no-changelog`
`--no-guide`		不在侧边栏显示	`--no-guide`
`--layout`		设置布局	`--layout doc`
`--tags`		设置标签	`--tags "教程,配置"`
`--dry-run`		预览模式	`--dry-run`
`--backup`	`-b`	创建备份	`--backup`
`--verbose`	`-v`	详细输出	`--verbose`
`--force`	`-f`	强制覆盖	`--force`
`--help`	`-h`	显示帮助	`--help`

标题同步器

功能描述

标题同步器可以自动将 index.md 文件中的 title frontmatter 同步到对应的 locales.json 文件中，用于侧边栏显示。

使用方法

bash

# 更新所有语言的标题
npm run update-titles

# 只更新中文标题
npm run update-titles zh

# 更新多个语言
npm run update-titles en zh

# 查看帮助
npm run update-titles -- --help

工作原理

扫描文件：查找包含 title frontmatter 的 index.md 文件
提取标题：解析 frontmatter 中的 title 字段
同步配置：将标题写入对应的 locales.json 文件
保护数据：完全保留其他已有配置

处理示例

处理前：

yaml

# docs/zh/guide/index.md
---
title: 用户指南
root: true
---

自动同步后：

json

// .vitepress/config/sidebar/zh/guide/locales.json
{
    "_self_": "用户指南",
    "getting-started.md": "快速开始",
    "advanced.md": "高级功能"
}

**处理前**：

```yaml
# docs/zh/guide/index.md
---
title: 用户指南
root: true
---
```

**自动同步后**：

```json
// .vitepress/config/sidebar/zh/guide/locales.json
{
    "_self_": "用户指南",
    "getting-started.md": "快速开始",
    "advanced.md": "高级功能"
}
```

Index.md 生成器

功能描述

Index.md 生成器可以扫描指定目录，为所有缺少 index.md 文件的文件夹自动创建索引文件。生成的 index.md 文件包含适当的 frontmatter 配置。

使用方法

bash

# 为指定目录创建缺少的 index.md 文件
npm run create-indexes -- -p docs/zh/guide

# 预览将要创建的文件
npm run create-indexes -- -p docs/zh --dry-run

# 使用自定义模板
npm run create-indexes -- -p docs/zh --template advanced

# 显示详细信息
npm run create-indexes -- -p docs/zh --verbose

模板类型

基础模板 (default)

yaml

---
title: 目录名称
root: true
---
# {{ $frontmatter.title }}

这是 `目录名称` 的索引页面。

请在此添加该部分的介绍内容。

高级模板 (advanced)

yaml

---
title: 目录名称
description: 目录名称相关文档
progress: 0
state: draft
root: true
outline: [2, 3]
showComment: true
gitChangelog: true
---

# {{ $frontmatter.title }}

## 简述 {#intro}

这是 `目录名称` 的索引页面。

## 内容概览 {#overview}

请在此添加该部分的介绍内容和导航信息。

## 相关链接 {#links}

- [相关文档](./related.md)
- [更多资源](./resources.md)

参数选项

参数	简写	描述	默认值
`--path`	`-p`	目标目录路径（必需）	-
`--template`	`-t`	模板类型	`default`
`--dry-run`	`-d`	预览模式	`false`
`--verbose`	`-v`	详细输出	`false`
`--force`	`-f`	覆盖现有文件	`false`
`--exclude`		排除模式	`[]`

侧边栏构建器在文档构建过程中自动运行，负责生成侧边栏配置。详细配置请参考。

bash

# 构建文档时自动运行
npm run docs:build

# 开发模式下自动监听
npm run docs:dev

全局配置：.sidebarrc.yml
本地配置：各目录的 index.md frontmatter
覆盖配置：.vitepress/config/sidebar/ 下的 JSON 文件

最佳实践

工作流建议

项目初始化：

bash

# 1. 为新项目创建 index.md 文件
npm run create-indexes -- -p docs/zh --template advanced

# 2. 设置基础 frontmatter
npm run update-frontmatter -- -p docs/zh --editor "你的名字" --state draft

# 3. 同步标题
npm run update-titles

内容维护：

bash

# 1. 预览更改
npm run update-frontmatter -- -p docs/zh/guide --progress 90 --dry-run

# 2. 应用更改
npm run update-frontmatter -- -p docs/zh/guide --progress 90 --backup

# 3. 同步标题
npm run update-titles zh

发布准备：

bash

# 1. 标记为已完成
npm run update-frontmatter -- -p docs/zh/completed --progress 100 --state published

# 2. 构建文档
npm run docs:build

脚本工具使用指南

简述

可用脚本概览

Frontmatter 编辑器

功能描述

支持的字段

基本用法

更新单个字段

更新多个字段

安全操作选项

高级功能

文件过滤

作者管理操作

批量状态管理

完整参数列表

标题同步器

功能描述

使用方法

工作原理

Index.md 生成器

功能描述

使用方法

模板类型

基础模板 (default)

高级模板 (advanced)

参数选项

侧边栏构建器

功能描述

自动触发

配置文件

最佳实践

工作流建议

安全注意事项

脚本工具使用指南 ​

简述 ​

可用脚本概览 ​

Frontmatter 编辑器 ​

功能描述 ​

支持的字段 ​

基本用法 ​

更新单个字段 ​

更新多个字段 ​

安全操作选项 ​

高级功能 ​

文件过滤 ​

作者管理操作 ​

批量状态管理 ​

完整参数列表 ​

标题同步器 ​

功能描述 ​

使用方法 ​

工作原理 ​

Index.md 生成器 ​

功能描述 ​

使用方法 ​

模板类型 ​

基础模板 (default) ​

高级模板 (advanced) ​

参数选项 ​

侧边栏构建器 ​

功能描述 ​

自动触发 ​

配置文件 ​

最佳实践 ​

工作流建议 ​

安全注意事项 ​

脚本工具使用指南

简述

可用脚本概览

Frontmatter 编辑器

功能描述

支持的字段

基本用法

更新单个字段

更新多个字段

安全操作选项

高级功能

文件过滤

作者管理操作

批量状态管理

完整参数列表

标题同步器

功能描述

使用方法

工作原理

Index.md 生成器

功能描述

使用方法

模板类型

基础模板 (default)

高级模板 (advanced)

参数选项

侧边栏构建器

功能描述

自动触发

配置文件

最佳实践

工作流建议

安全注意事项