目录结构

组织 Jamdesk 文档仓库中的文件，从最少两个文件到完整的多目录布局。

最小结构

最简单的 Jamdesk 项目只需要两个文件：

my-docs/
├── docs.json           # Configuration
└── introduction.mdx    # Your first page

推荐结构

对于较大的文档站点，将页面组织到目录中：

my-docs/
├── docs.json
├── introduction.mdx
├── quickstart.mdx
│
├── guides/
│   ├── getting-started.mdx
│   ├── authentication.mdx
│   └── deployment.mdx
│
├── api-reference/
│   ├── overview.mdx
│   ├── endpoints/
│   │   ├── users.mdx
│   │   └── projects.mdx
│   └── webhooks.mdx
│
├── images/
│   ├── logo.svg
│   ├── favicon.svg
│   └── screenshots/
│       └── dashboard.png
│
└── snippets/
    └── api-base-url.mdx

必需文件

docs.json

定义站点的配置文件。必须位于文档目录的根目录中（或项目设置中指定的路径）。

{
  "$schema": "https://jamdesk.com/docs.json",
  "name": "My Documentation",
  "theme": "jam",
  "colors": {
    "primary": "#635BFF"
  },
  "navigation": {
    "groups": [
      {
        "group": "Getting Started",
        "pages": ["introduction", "quickstart"]
      }
    ]
  }
}

所有选项请参阅 docs.json 参考。

页面组织

扁平结构与嵌套结构

根据文档规模进行选择：

docs/
├── docs.json
├── introduction.mdx
├── installation.mdx
├── configuration.mdx
└── troubleshooting.mdx

"pages": ["introduction", "installation"]

命名约定

特殊目录

images/

存储图片、徽标和网站图标：

images/
├── logo-light.webp     # Light mode logo
├── logo-dark.webp      # Dark mode logo
├── favicon.svg         # Browser favicon
└── screenshots/        # Documentation screenshots
    └── dashboard.png

在 docs.json 中引用：

{
  "logo": {
    "light": "/images/logo-light.webp",
    "dark": "/images/logo-dark.webp"
  },
  "favicon": "/images/favicon.svg"
}

snippets/

可复用的内容块：

snippets/
├── api-base-url.mdx
└── auth-header.mdx

在页面中引入：

<Snippet file="api-base-url.mdx" />

openapi/

用于 API 文档的 OpenAPI 规范文件：

openapi/
├── api.yaml
└── webhooks.yaml

在 docs.json 中引用：

{
  "api": {
    "openapi": ["/openapi/api.yaml"]
  }
}

实际示例请参阅 OpenAPI 示例。

特定语言的规范文件

对于多语言文档站点，请在源文件旁添加带语言代码中缀的翻译规范文件：

openapi/
├── api.yaml
├── api.fr.yaml
├── api.es.yaml
└── api.zh.yaml

当页面在语言前缀（/fr/…、/es/… 等）下渲染时，Jamdesk 会自动提供正确的规范文件。有关需要翻译和需要保持一致的内容的完整规则，请参阅多语言支持 → 翻译 OpenAPI 规范。

忽略的文件

创建 .gitignore 以排除构建产物：

.jamdesk/
node_modules/
.DS_Store
*.log

.jamdesk/ 目录保存本地开发缓存。请勿提交它。

下一步