shane-new-doc 使用指南

shane-new-doc 装好之后（见安装与快速开始），会在项目里生成 scripts/new-doc.js，有两种用法。如果运行 pnpm new-doc 提示脚本不存在，看验证是否装成功——简单说就是有些包管理器会跳过初始化这一步，安装原理详解里讲清楚了为什么会这样、以及怎么手动补上。

方式一：交互模式

不带任何参数直接运行：

npm run new-doc

pnpm new-doc

yarn new-doc

会依次问：

必填相对 src/content/docs/ 的子目录，留空会一直重复问。

文件名

必填立刻做非法字符检查，不合法会重新提示输入。

标题 / 描述

可选都可以直接回车跳过。

排序

可选对应 frontmatter 里的 sidebar.order，必须是数字或留空，输入非数字会重新提示。

标题留空的话，会自动用文件名（去掉扩展名）当标题。

方式二：命令模式

前两个位置参数必须依次是目录和文件名，顺序固定不能打乱——这是整条命令里唯一不能重排的部分。它们后面的每一项都是 key:value，和前两个位置参数不同，这些参数顺序随意，用 / 分隔（也可以用空格 + 结尾 \ 换行分隔）：

pnpm new-doc "guide" "getting-started" title:Getting Started/description:Intro to the project/order:1/mdx:T

下面这样写效果完全一样——同样的键，换了个顺序：

pnpm new-doc "guide" "getting-started" \
  mdx:T \
  order:1 \
  title:Getting Started \
  description:Intro to the project

参数表

参数	别名	是否必填	说明
`directory`	`dir`	是	位置参数 #1，相对 `src/content/docs/`。
`filename`	—	是	位置参数 #2。
`title`	—	否	文档标题，不写就默认用文件名（去掉扩展名）。
`description`	`desc`	否	文档描述，为空时 frontmatter 里直接不写这个字段。
`order`	`sidebarorder`	否	侧边栏排序。只要填了就必须是数字，填了非数字会直接报错并终止命令。
`mdx`	—	否	布尔值，规则见下方。`T`/`true` 生成 `.mdx`，否则生成 `.md`。

布尔类型的 mdx 参数规则和 shane-new-post 一样：不区分大小写，只有 t / true（任意大小写）会被识别为“是”。f、false、空值，或者不写这个参数，都会被当成“否”——同样没有专门判断“false”的逻辑，凡是不匹配“true”的都落到默认值。

会生成什么

文件夹src/
- 文件夹content/
  - 文件夹docs/
    文件夹guide/
    getting-started.md 新文档，sidebar order 为 1
文件夹public/
- 文件夹img/
  - 文件夹guide/
    文件夹getting-started/ 同名配图文件夹，空的
    …

其它行为

只有项目依赖里检测到 @astrojs/starlight 才会生成/管理脚本，不会误装进无关项目。
同名文件已存在时不会覆盖，会自动在文件名后加 (2)、(3) 这样的序号，并打印提示。
每次新建文档都会自动创建对应子目录下同名的配图文件夹。
支持 .md 和 .mdx；如果文件名本身已经带了这两种扩展名之一，会原样使用，并提示 mdx 参数被忽略。
目录 / 文件名只要解析结果会跑出 src/content/docs/ 之外（比如靠 ..），一律拒绝，即便非法字符检查被绕过也会在这一步拦下来。