Jamdesk Documentation logo

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 或更高版本(推荐)

快速开始

1
Create a Project

创建新的文档项目:

jamdesk init my-docs
cd my-docs
2
Start Development Server

运行带热重载的本地开发服务器:

jamdesk dev

您的文档运行在 http://localhost:3000/docs

3
Validate Before Deploying

检查配置错误、失效链接和拼写:

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 中。

Authentication Guide

基于浏览器的认证流程、会话管理和故障排除

清除已存储的凭据。

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 fix

dry-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 或更高版本
Fix Broken Links Guide

分步指南:预览、应用、审核和提交

查看或更改项目的 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)
Fix with AI

各模式的作用以及如何撤销自动修复

检查文档中的拼写错误。

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 中添加项目专用术语:

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 语法问题

该命令具有幂等性,重复运行是安全的。

Migration Guide

完整的迁移指南,包含 Mintlify 及其他平台的分步说明

部署

将 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 副本。其文件将保留为未提交的更改
Edit on your computer

发布、合并 Jamdesk 更改、冲突处理以及 deploy 拒绝的文件

从终端上传文档并触发构建。

jamdesk deploy
jamdesk deploy --detach
jamdesk deploy --full-rebuild

CLI 会在每个构建阶段完成时显示进度。也可以使用 jamdesk push。

参数说明
--detach加入队列后立即退出
--full-rebuild强制完整重建(不使用缓存)
--project <id>部署到指定项目
--allow-empty允许在没有任何 .mdx 内容页面的情况下部署(默认拒绝)
-m, --message <text>在由 jamdesk pull 创建的文件夹中使用的提交信息
--allow-secret-files从由 jamdesk pull 创建的文件夹中发布疑似机密的文件
CLI Deploy Guide

完整的部署流程、构建阶段、错误参考和故障排除

搭建并部署一个 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 模式)。从不部署,也从不覆盖已有目录
Cloudflare Workers Guide

Worker 设置、路由模式和缓存配置

维护

检查您的环境并诊断问题。

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
}
选项类型默认值说明
defaultPortnumber3000开发服务器的默认端口
verbosebooleanfalse默认启用详细输出
checkUpdatesbooleantrue启动时检查 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 &lt; or rewrite

解决方法:

  • 对字面量小于号使用 &lt;:Values &lt;50% are low
  • 改写以避免该字符:使用 "Below 50%" 代替 "<50%"
  • 运行 jamdesk validate 获取包含行号的详细错误信息

请在包含 docs.json 文件的目录中运行该命令。

解决方法:

  • 运行 jamdesk init 创建新项目
  • 确认您位于正确的目录
  • 确认文件名确为 docs.json(而不是 doc.json 等)

请尝试以下步骤:

  1. 运行 jamdesk doctor 检查您的环境
  2. 运行 jamdesk clean 清除缓存
  3. 使用 jamdesk dev --verbose 获取详细的错误输出
  4. 检查是否已安装 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 }

您可能没有缓存目录的写入权限。

解决方法:

  1. 检查 ~/.jamdesk 的权限:ls -la ~/.jamdesk
  2. 修复所有权:sudo chown -R $(whoami) ~/.jamdesk
  3. 运行 jamdesk clean 后重试

仍有问题? 请查看 CLI 故障排除指南,或在 GitHub 上提交 issue。

下一步

Authentication

登录流程、会话和故障排除

CLI Deploy

从终端部署

Local Preview

高级本地开发选项

Migration Guide

从 Mintlify 或其他平台迁移