官网主题首页配置说明

觅思文档提供了可高度自定义的“官网主题首页”，通过配置一个结构化的 JSON 对象，即可自由搭建类似产品官网一样的首页展示。本文将详细介绍各字段结构、功能说明和使用示例。

---

## 1. 配置文件整体结构

官网主题首页配置主要包含三个顶级字段：

```jsonc
{
    "theme": "minimal",
    "cover": { ... },
    "blocks": [ ... ]
}
```

### 字段说明

| 字段名        | 类型     | 说明                                        |
| ---------- | ------ | ----------------------------------------- |
| **theme**  | string | 主题风格标识，默认为 `"minimal"`，支持`business`、`tech`   |
| **cover**  | object | 首页顶封面（大 banner）配置                         |
| **blocks** | array  | 首页主体内容的区块列表，每个区块可以是 feature / section 等类型 |

---

## 2. cover —— 顶部封面配置

```jsonc
"cover":{
    "title": "MrDoc",
    "subtitle": "A Self-Hosted Knowledge Base & Wiki Platform.",
    "bg_theme": "green",
    "ctas":[
        {"text":"Live Demo","link":"http://demo.mrdoc.pro","type":"primary","target":"_blank"},
        {"text":"Get Started","link":"https://mrdoc.io/p/deploy_guide/","type":"primary","target":"_blank"},
        {"text": "GitHub", "link": "https://github.com/zmister2016/MrDoc", "type": "primary","target":"_blank"}
    ]
}
```

### 字段说明

| 字段           | 类型     | 说明                                             |
| ------------ | ------ | ---------------------------------------------- |
| **title**    | string | 封面大标题                                          |
| **subtitle** | string | 标题下描述文字                                        |
| **bg_theme** | string | 顶部封面的背景图，可选择`minimal`, `green`, `business`, `tech`,`sunset`） |
| **ctas**     | array  | 按钮数组（Call to Action）                           |

#### CTA 按钮字段说明

| 字段         | 说明                   |
| ---------- | -------------------- |
| **text**   | 按钮文字                 |
| **link**   | 跳转链接                 |
| **type**   | 按钮样式类型，如 `primary`   |
| **target** | 是否新窗口打开，通常为 `_blank` |

---

## 3. blocks —— 首页主体区块配置

`blocks` 是一个数组，每一个区块是一个模块，可以展示不同内容。

当前支持两类模块：

1. **feature** 模块：用于展示一组图标+标题+描述
2. **section** 模块：左右排版，带大图与按钮的内容段落
3. **project** 模块：以`feature`的形式展示文集列表

下面分别说明。

---

### 3.1 feature 模块（图标特性展示）

#### 示例：

```jsonc
{
    "type":"feature",
    "title":"Why Choose MrDoc?",
    "subtitle": "MrDoc is a versatile...",
    "contents":[
        {
            "title": "Full Data Control",
            "desc": "Host your knowledge base...",
            "icon": "http://xxx.svg"
        }
    ],
    "bg_color":"bg-muted-gradient"
}
```

#### 字段说明

| 字段           | 类型        | 说明                                                              |
| ------------ | --------- | --------------------------------------------------------------- |
| **type**     | "feature" | 固定为 feature                                                     |
| **title**    | string    | 模块主标题                                                           |
| **subtitle** | string    | 模块描述（可选）                                                        |
| **contents** | array     | 图标特性数组                                                          |
| **bg_color** | string    | 背景样式，可选（示例：`bg-light`, `bg-light-gradient`, `bg-dark-gradient`） |

#### contents（特性项）字段说明

| 字段        | 说明                |
| --------- | ----------------- |
| **title** | 特性标题              |
| **desc**  | 内容描述              |
| **icon**  | 图标 URL（SVG 或 PNG） |

---

### 3.2 section 模块（图文左右布局）

适合用于展示产品模块、功能说明、宣传介绍等。

#### 示例

```jsonc
{
    "type": "section",
    "contents": [
        {
            "title": "Multi-Format Document Creation",
            "desc": "Easily create various document types...",
            "img": "http://xxx.png",
            "align": "right",
            "btns": [
                {"text": "View Example", "url": "xxx"}
            ],
            "bg_color": "bg-light"
        }
    ]
}
```

#### 字段说明（section → contents 内项）

| 字段           | 说明                                    |
| ------------ | ------------------------------------- |
| **title**    | 小节标题                                  |
| **desc**     | 小节描述，可以包含较长内容                         |
| **img**      | 右侧或左侧的大图                              |
| **align**    | 图文排版方向<br/>`left`：图在左<br/>`right`：图在右 |
| **btns**     | 按钮列表，可选                               |
| **bg_color** | 背景色，可选                                |

#### btns 字段说明

| 字段       | 说明   |
| -------- | ---- |
| **text** | 按钮文字 |
| **url**  | 跳转链接 |

### 3.3 project 模块（文集列表展示）

适合展示指定的文集

#### 示例

```
{
    "type": "project",
    "title": "所有文集",
    "subtitle":"这是有最新文档的文集块",
    "contents": [
        {"remark": "第一个文集","id": "4",},
        {"remark": "第二个文集","id": "13",},
        {"remark": "第二个文集","id": "13",},
        {"remark": "第二个文集","id": "13",},
        {"remark": "第二个文集","id": "13",},
    ],
    "bg_color": "bg-dark-gradient"
},
{
    "type": "project_desc",
    "title": "所有文集",
    "subtitle":"这是有文集简介的文集块",
    "contents": [
        {"remark": "第一个文集","id": "4",},
        {"remark": "第二个文集","id": "13",},
        {"remark": "第二个文集","id": "13",},
        {"remark": "第二个文集","id": "13",},
        {"remark": "第二个文集","id": "13",},
    ],
    "bg_color": "bg-dark-gradient"
},
```

#### 字段说明

| 字段           | 类型        | 说明                                                              |
| ------------ | --------- | --------------------------------------------------------------- |
| **type**     | string | project或project_desc                                                     |
| **title**    | string    | 模块主标题                                                           |
| **subtitle** | string    | 模块描述（可选）                                                        |
| **contents** | array     | 文集列表数组                                                          |
| **bg_color** | string    | 背景样式，可选（示例：`bg-light`, `bg-light-gradient`, `bg-dark-gradient`） |

#### contents（文集）字段说明

| 字段        | 说明                |
| --------- | ----------------- |
| **remark** | 备注，不会显示在网页上              |
| **id**  | 文集的ID              |

---

## 4. 更多可配置内容示例

### 4.1 Use Cases（场景应用展示）

使用 feature 模块展示不同使用场景：

```jsonc
{
    "type": "feature",
    "title": "Use Cases",
    "contents": [
        {
            "title": "Knowledge Management",
            "desc": "Organize knowledge...",
            "icon": "..."
        }
    ],
    "bg_color": "bg-dark-gradient"
}
```

### 4.2 Who Is MrDoc For?（适用人群）

图标可缺省，描述文本居多：

```jsonc
{
    "type":"feature",
    "title":"Who Is MrDoc For?",
    "contents":[
        {"title": "Product Managers & Startups", "desc": "..."},
        {"title": "IT & System Administrators", "desc": "..."}
    ]
}
```

### 4.3 Editions & Services（版本与服务）

同样使用 feature 模块，但特性项支持按钮：

```jsonc
{
    "type": "feature",
    "title": "Editions & Services",
    "contents": [
        {
            "title": "Open Source Edition",
            "icon": "...",
            "desc": "Free self-hosted knowledge base...",
            "btns": [
                {"text": "View Demo", "url": "http://demo.mrdoc.pro"},
                {"text": "Get Started", "url": "https://github.com/zmister2016/MrDoc"}
            ]
        }
    ]
}
```

---

## 5. 如何开始编写首页配置

### 步骤 1：编辑配置数据

官网主题首页配置使用的是JSON数据格式，推荐使用代码编辑器或在线JSON格式化网页中进行编辑，例如：VSCode、https://www.sojson.com/

### 步骤 2：后台填入

编辑好配置数据后，在后台管理-站点设置-首页模板中选择「官网主题」，然后将配置数据填入下面的文本框中。

### 步骤 3：保存后刷新首页

点击保存后，系统会根据配置自动渲染模板。

---

## 6. 小技巧与建议

### ✔ 建议图标使用 SVG

清晰、轻量、可在深色背景下保持一致效果。

### ✔ `align` 建议左右交替

使页面视觉更有节奏感。

### ✔ 背景色 `bg_color` 可穿插使用

如：`bg-light`、`bg-dark-gradient`、`bg-muted-gradient`
能提升对比度和阅读体验。

---

## 7. 完整最小示例（可复制）

```jsonc
{
    "theme": "minimal",
    "cover": {
        "title": "MySite",
        "subtitle": "Your Knowledge Hub.",
        "bg_theme": "green",
        "ctas": [
            {"text":"Get Started","link":"https://example.com/start","type":"primary","target":"_blank"}
        ]
    },
    "blocks": [
        {
            "type":"feature",
            "title":"Features",
            "contents":[
                {"title":"Fast","desc":"Super fast engine","icon":"https://example.com/fast.svg"},
                {"title":"Secure","desc":"Your data is safe","icon":"https://example.com/secure.svg"}
            ]
        },
        {
            "type":"section",
            "contents":[
                {"title":"Markdown Editing","desc":"Write comfortably.","img":"https://example.com/editor.png","align":"right"}
            ]
        }
    ]
}
```