CLI 概览
使用开源的 Jamdesk CLI 在本地预览文档、验证配置、检查失效链接,并从其他平台迁移。
Jamdesk CLI 可让您在本地预览文档、验证配置、检查失效链接,并从其他平台迁移。它基于 Apache License 2.0 开源。
安装
从 npm 全局安装,即可在任意位置使用 jamdesk:
npm install -g jamdesk验证安装:
jamdesk --version
系统要求
- Node.js 22.18+ 或 24.11+(不支持 Node.js 23)
- npm v8 或更高版本(推荐)
快速开始
创建新的文档项目:
jamdesk init my-docs
cd my-docs检查配置错误、失效链接和拼写:
jamdesk validate
jamdesk broken-links
jamdesk fix --dry-run
jamdesk fix
jamdesk spellcheck命令
运行 jamdesk <command> --help 可查看任意命令的详细信息。
开发
启动带热重载的本地开发服务器。
jamdesk dev
jamdesk dev --port 3001功能:
- 启动时自动验证(docs.json 结构、MDX 语法以及引用的 OpenAPI 规范。规范无效时服务器会停止。)
- MDX 文件变更时热重载
- docs.json 变更时自动重建导航
- 浏览器刷新时重新加载自定义 CSS(
style.css) - 搜索
- 所有主题和组件
选项:
| 参数 | 说明 |
|---|---|
-p, --port <port> | 运行端口(默认:3000) |
-v, --verbose | 启用详细输出 |
创建新的文档项目。
jamdesk init # Interactive mode
jamdesk init my-docs # Create in new directory这会创建一个包含以下内容的新项目:
docs.json配置文件- 示例 MDX 页面
- 推荐的文件夹结构
身份验证
通过浏览器登录 Jamdesk。部署前需要先登录。
jamdesk login会在浏览器中打开 Jamdesk 控制台。CLI 将凭据存储在 ~/.jamdeskrc 中。
清除已存储的凭据。
jamdesk logout显示当前登录的用户并验证会话。
jamdesk whoami验证
验证您的 docs.json 配置、MDX 语法和 OpenAPI 规范。
jamdesk validate
jamdesk validate --skip-mdx检查内容:
- docs.json 中的 JSON 语法是否有效
- 必填字段(name、navigation)
- 主题值是否有效
- MDX 语法错误(例如未转义的
<字符) - OpenAPI 规范验证(如已配置)
- 结构合规性
选项:
| 参数 | 说明 |
|---|---|
--skip-mdx | 跳过 MDX 语法验证 |
-v, --verbose | 显示详细的验证输出 |
部署前运行此命令,可及早发现错误。
扫描文档中失效的内部链接。
jamdesk broken-links示例输出:
docs/getting-started.mdx:15 - /docs/quikstart
Did you mean: /docs/quickstart
Found 1 broken link in 45 files.检测指向缺失页面的链接和拼写错误。详情请参阅 链接与导航。
自动修复目标明确的内部链接警告。它可修复两类问题:
- 拼写错误的锚点:如
#instalation这类明显应为#installation的片段 - 跨语言锚点偏移:译文页面重命名了标题,但该语言版本中的链接仍指向旧的英文片段
# Preview what would change without touching any files
jamdesk fix --dry-run
# Apply fixes (prompts for confirmation)
jamdesk fixdry-run 示例输出:
Planned fixes:
fr/ai/overview.mdx:9
/fr/ai/selectors#ai-strategies → /fr/ai/selectors#stratégies-ia
(dry run — no files written)仅当修正后的锚点在目标页面上确实对应一个真实标题时,jamdesk fix 才会写入修复。存在歧义的情况会留给人工审核。
选项:
| 参数 | 说明 |
|---|---|
--dry-run | 预览计划中的修复,不写入任何文件 |
-y, --yes | 无需确认提示直接应用修复 |
--types <list> | 要修复的警告类型,以逗号分隔(默认:所有受支持的类型) |
--no-ai | 跳过 AI 修复,仅使用 Jamdesk 无需 AI 即可确定的修复 |
--project <id> | AI 修复所用的项目 ID(默认:docs.json 中的 projectId) |
--json | 以 JSON 格式输出修复计划以及无法修复的问题,供 AI 代理使用。不写入文件,也不询问。需要 CLI 1.1.229 或更高版本 |
查看或更改项目的 AI Fixes 设置,与控制台“设置”中的相同。
# Show the current setting
jamdesk ai-fix
# Commit fixes to your build branch after each build
jamdesk ai-fix auto
# Suggest fixes for you to review in the dashboard
jamdesk ai-fix review
# Turn off dashboard scans
jamdesk ai-fix off示例输出:
✓ AI Fixes set to Auto-fix
Jamdesk commits fixes to main after the next build. Pull before you push. Undo runs from the dashboard.请先运行 jamdesk login。该命令使用 docs.json 中的 projectId,或您通过 --project 指定的项目。需要 CLI 1.1.229 或更高版本。
| 参数 | 说明 |
|---|---|
--project <id> | 项目 ID(默认:docs.json 中的 projectId) |
检查文档中的拼写错误。
jamdesk spellcheck示例输出:
getting-started.mdx:14 - "recieve"
└─ Did you mean: receive
Found 3 misspellings across 24 pages.
Tip: Run "jamdesk spellcheck --fix" to interactively fix or ignore words.使用英文词典,内置 150 多个技术术语(API、GraphQL、Kubernetes、React 等)。会跳过代码块、行内代码、frontmatter、JSX、URL 和文件路径。目前仅支持英文,多语言词典已在规划中。
选项:
| 参数 | 说明 |
|---|---|
--fix | 交互式修复拼写错误或加入忽略列表 |
--json | 以 JSON 格式输出(用于 CI 流水线) |
-v, --verbose | 显示每个被检查的文件 |
交互式修复模式(--fix) 会逐个处理每个不重复的拼写错误单词:
1/10 "recieve" — found in 3 files
intro.mdx:14, setup.mdx:7, guide.mdx:22
? What do you want to do?
❯ Fix → receive (recommended)
Fix → relieve
Ignore in the future (add to docs.json)
Skip- Fix 会在每个文件中用建议词替换该单词。它绝不会修改代码块或 JSX 属性。提示最多显示 3 个建议,并标记最佳匹配项为推荐。
- Ignore 会将该单词添加到 docs.json 的
spellcheck.ignore中,之后不再被标记。 - Skip 本次运行不做任何处理
更改会在应用前供您预览并确认。
自定义忽略列表: 在 docs.json 中添加项目专用术语:
{
"spellcheck": {
"ignore": ["YourProduct", "kubectl", "Terraform"]
}
}拼写检查会忽略 docs.json 中的项目名称。
验证单个 OpenAPI 规范文件。
jamdesk openapi-check openapi.yaml
jamdesk openapi-check api/spec.json验证内容:
- YAML/JSON 语法是否有效
- 是否符合 OpenAPI 3.x 结构
- 端点定义
$ref引用是否能正确解析
Jamdesk 在三个位置验证 OpenAPI 规范。 若引用的规范无效,jamdesk dev 启动时会停止。jamdesk validate 和 jamdesk openapi-check 按需检查规范。云端构建会在部署时检查引用的规范,此时无效规范属于非致命警告,文档的其余部分仍会发布。邮件和控制台的构建列表会指出问题:包含行号和列号的解析错误、无法解析的 $ref,或重复的 operationId。修复规范并再次推送即可清除该警告。
文件管理
重命名页面并更新所有对它的引用。
jamdesk rename docs/old-name.mdx docs/new-name.mdx此操作将:
- 重命名文件
- 更新 docs.json 中的导航
- 更新所有其他 MDX 文件中的链接
- 更新代码片段引用
请使用此命令代替手动重命名,以保持引用同步。
迁移
将文档从 Mintlify 迁移到 Jamdesk。
jamdesk migrate会检测您的 Mintlify 配置并将其转换为 Jamdesk 格式。同一过程还会:
- 重命名已弃用的组件(例如
CardGroup→Columns) - 将孤立的代码片段 MDX 文件移入
/snippets/,并重写父级相对导入 - 将使用 React Hooks 的内联组件提取为带
'use client'的/snippets/<name>.tsx - 修复机械性的 MDX 语法问题
该命令具有幂等性,重复运行是安全的。
部署
将 Jamdesk 托管文档的项目(不使用 GitHub)下载为 git 仓库,或将 Jamdesk 的新更改合并到您已拉取的副本中。
jamdesk pull
jamdesk pull --project your-project
jamdesk pull --dir ./docs-copy编辑文件后,在该文件夹中运行 jamdesk deploy 即可发布。需要 CLI 1.1.227 或更高版本以及 git。
| 参数 | 说明 |
|---|---|
--project <id-or-slug> | 拉取指定项目(跳过交互式选择) |
--dir <path> | 目标文件夹(默认:./<slug>) |
--force | 将已有文件的文件夹(例如旧的只读副本)转换为 git 副本。其文件将保留为未提交的更改 |
从终端上传文档并触发构建。
jamdesk deploy
jamdesk deploy --detach
jamdesk deploy --full-rebuildCLI 会在每个构建阶段完成时显示进度。也可以使用 jamdesk push。
| 参数 | 说明 |
|---|---|
--detach | 加入队列后立即退出 |
--full-rebuild | 强制完整重建(不使用缓存) |
--project <id> | 部署到指定项目 |
--allow-empty | 允许在没有任何 .mdx 内容页面的情况下部署(默认拒绝) |
-m, --message <text> | 在由 jamdesk pull 创建的文件夹中使用的提交信息 |
--allow-secret-files | 从由 jamdesk pull 创建的文件夹中发布疑似机密的文件 |
搭建并部署一个 Cloudflare Worker,将您自有域名上的 /docs 代理到您的 Jamdesk 站点。
jamdesk deploy-proxy cloudflare
jamdesk deploy-proxy cloudflare --slug myproject --domain example.com --yes该命令默认为交互模式。它会检查 Wrangler、验证您的 Cloudflare 账户、从 docs.json 检测 slug、生成 Worker 文件,并询问是否部署。--yes 仅生成文件然后停止。随后可在输出目录中运行 npx wrangler deploy 进行部署。
| 参数 | 说明 |
|---|---|
--slug <slug> | Jamdesk 项目 slug |
--domain <domain> | 目标域名(例如 example.com) |
--path <path> | 路径前缀(默认:/docs) |
--output-dir <dir> | 输出目录(默认:cloudflare-worker/) |
--skip-deploy | 在交互式运行中跳过"立即部署?"提示 |
--force | 若输出目录已存在则覆盖 |
--yes | 对每个提示使用默认值(CI 模式)。从不部署,也从不覆盖已有目录 |
维护
检查您的环境并诊断问题。
jamdesk doctor检查项:
- Node.js 版本(需要 22.18+ 或 24.11+)
- PATH 中优先的 Node.js(
jamdesk dev使用它运行) - npm 版本
- docs.json 是否存在且有效
- ~/.jamdesk 缓存状态
- 写入权限
CLI 运行异常时运行此命令。
清除 ~/.jamdesk 缓存目录。
jamdesk clean此操作会删除已缓存的依赖和构建产物。可用于:
- 释放磁盘空间
- 修复损坏的缓存
- 强制重新安装依赖
下一次 jamdesk dev 会重新安装依赖。
将 CLI 更新到最新版本。
jamdesk update您也可以手动更新:
npm update -g jamdesk配置
创建 ~/.jamdeskrc 以设置默认选项:
{
"defaultPort": 3001,
"verbose": false,
"checkUpdates": true
}
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
defaultPort | number | 3000 | 开发服务器的默认端口 |
verbose | boolean | false | 默认启用详细输出 |
checkUpdates | boolean | true | 启动时检查 CLI 更新 |
故障排除
MDX 以 JSX 方式解析,某些字符具有特殊含义。
常见问题: < 字符被解释为 JSX 标签的开始。
✗ Found 1 MDX syntax error(s)
getting-started.mdx:42
Unexpected character `5` (U+0035) before name
Fix: A < character is being parsed as JSX. Use < or rewrite解决方法:
- 对字面量小于号使用
<:Values <50% are low - 改写以避免该字符:使用
"Below 50%"代替"<50%" - 运行
jamdesk validate获取包含行号的详细错误信息
请在包含 docs.json 文件的目录中运行该命令。
解决方法:
- 运行
jamdesk init创建新项目 - 确认您位于正确的目录
- 确认文件名确为
docs.json(而不是doc.json等)
请尝试以下步骤:
- 运行
jamdesk doctor检查您的环境 - 运行
jamdesk clean清除缓存 - 使用
jamdesk dev --verbose获取详细的错误输出 - 检查是否已安装 Node.js 22.18+ 或 24.11+:
node --version
首次运行时会将依赖安装到 ~/.jamdesk/node_modules。
此过程只发生一次,之后的运行会更快。
该默认端口已被其他进程占用。
解决方法:
# Use a different port
jamdesk dev --port 3001
# Or set a default in ~/.jamdeskrc
{ "defaultPort": 3001 }您可能没有缓存目录的写入权限。
解决方法:
- 检查
~/.jamdesk的权限:ls -la ~/.jamdesk - 修复所有权:
sudo chown -R $(whoami) ~/.jamdesk - 运行
jamdesk clean后重试
仍有问题? 请查看 CLI 故障排除指南,或在 GitHub 上提交 issue。
