---
title: 目录结构
description: "了解如何组织 Jamdesk 文档仓库中的文件：必需文件、页面目录、图片、代码片段和 OpenAPI 规范。"
---
> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.
本页介绍如何组织 Jamdesk 文档仓库中的文件，从最少的两个文件到完整的多目录布局。
## 最小结构
最简单的 Jamdesk 项目只需要两个文件：
```bash
my-docs/
├── docs.json # Configuration
└── introduction.mdx # Your first page
```
## 推荐结构
对于较大的文档站点，可以将页面整理到不同目录中：
```bash
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
```
[Jamdesk 文档仓库](https://github.com/jamdesk/jamdesk-docs)是这种结构的生产示例：包含两个标签页、120 多个页面、OpenAPI 规范和自定义脚本。
## 必需文件
### docs.json
用于定义站点的配置文件。必须位于文档目录的根目录中（或项目设置中指定的路径）。
```json 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 参考](/cn/config/docs-json-reference)。
## 页面组织
### 扁平结构与嵌套结构
根据文档规模进行选择：
将所有页面保存在根目录中：
```bash
docs/
├── docs.json
├── introduction.mdx
├── installation.mdx
├── configuration.mdx
└── troubleshooting.mdx
```
在导航中直接引用页面：
```json
"pages": ["introduction", "installation"]
```
将相关页面归类到不同目录中：
```bash
docs/
├── docs.json
├── introduction.mdx
├── guides/
│ ├── quickstart.mdx
│ └── advanced.mdx
└── reference/
├── api.mdx
└── cli.mdx
```
在路径中包含目录：
```json
"pages": ["introduction", "guides/quickstart", "reference/api"]
```
### 命名约定
| 约定 | 示例 | URL |
|------------|---------|-----|
| 小写 | `getting-started.mdx` | `/getting-started` |
| 短横线命名 | `api-reference.mdx` | `/api-reference` |
| 目录 | `guides/auth.mdx` | `/guides/auth` |
避免在文件名中使用空格和特殊字符。使用短横线分隔单词。
## 特殊目录
### images/
存储图片、徽标和网站图标：
```bash
images/
├── logo-light.webp # Light mode logo
├── logo-dark.webp # Dark mode logo
├── favicon.svg # Browser favicon
└── screenshots/ # Documentation screenshots
└── dashboard.png
```
在 docs.json 中引用：
```json docs.json
{
"logo": {
"light": "/images/logo-light.webp",
"dark": "/images/logo-dark.webp"
},
"favicon": "/images/favicon.svg"
}
```
### snippets/
可复用的内容块：
```bash
snippets/
├── api-base-url.mdx
└── auth-header.mdx
```
在页面中引入：
```mdx
```
### openapi/
用于 API 文档的 OpenAPI 规范文件：
```bash
openapi/
├── api.yaml
└── webhooks.yaml
```
在 docs.json 中引用：
```json docs.json
{
"api": {
"openapi": ["/openapi/api.yaml"]
}
}
```
如需查看实际示例，请参阅 [OpenAPI 示例](/cn/api-reference/openapi-example)。
#### 特定语言的规范文件
对于多语言文档站点，可以在源文件旁添加带语言代码插入标识的翻译规范文件：
```bash
openapi/
├── api.yaml
├── api.fr.yaml
├── api.es.yaml
└── api.zh.yaml
```
当页面在语言前缀下（`/fr/…`、`/es/…` 等）渲染时，Jamdesk 会自动提供正确的规范文件。有关哪些内容需要翻译、哪些内容必须保持一致的完整规则，请参阅[多语言支持 → 翻译 OpenAPI 规范](/cn/setup/languages#翻译-openapi-规范)。
## 忽略的文件
创建 `.gitignore` 以排除构建产物：
```bash
.jamdesk/
node_modules/
.DS_Store
*.log
```
`.jamdesk/` 目录包含本地开发缓存，不应提交到版本控制系统。
## 下一步
配置 monorepo 的文档路径
所有配置选项