Jamdesk Documentation logo

CLI 概览

使用开源 Jamdesk CLI 在本地预览文档、验证配置、检查断链并迁移平台。

Jamdesk CLI 可用于在本地预览文档、验证配置、检查断链，以及从其他平台迁移。它基于 Apache License 2.0 开源。

安装

从 npm 全局安装，即可在任意位置使用 jamdesk：

npm install -g jamdesk

安装后，验证 CLI 是否正常运行：

jamdesk --version

要求

  • Node.js v20.0.0 或更高版本
  • 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 仪表板进行身份验证。凭据会存储在本地 ~/.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 fix

试运行输出示例：

Planned fixes:

  fr/ai/overview.mdx:9
    /fr/ai/selectors#ai-strategies  →  /fr/ai/selectors#stratégies-ia

(dry run — no files written)

只有在修正后的锚点能够解析到目标页面中的真实标题时，才会写入修复结果。存在歧义的情况会留待手动检查。

选项：

标志描述
--dry-run预览计划中的修复，不写入任何文件
-y, --yes无需确认提示即可应用修复
--types <list>要修复的警告类型，以逗号分隔（默认为所有受支持的类型）
断链修复指南

分步介绍预览、应用、检查和提交修复

检查文档中的拼写错误。

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 引用可正确解析

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 的内联组件提取到 /snippets/<name>.tsx 并添加 'use client'，以及自动修复机械性的 MDX 语法问题。该命令具有幂等性，因此可以安全地重复运行。

迁移指南

面向 Mintlify 和其他平台的完整分步迁移指南

部署

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

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

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

标志描述
--detach将任务加入队列后立即退出
--full-rebuild强制完整重建（不使用缓存）
--project <id>部署到指定项目
--allow-empty允许部署包含零个 .mdx 内容页面的项目（默认拒绝）
CLI 部署指南

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

构建并部署 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 指南

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

维护

检查环境并诊断问题。

jamdesk doctor

检查内容：

  • Node.js 版本（要求 v20+）
  • 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 v20+：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 上提交问题。

接下来做什么？

身份验证

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

CLI 部署

从终端进行部署

本地预览

高级本地开发选项

迁移指南

从 Mintlify 或其他平台迁移