Official website theme homepage configuration instructions

# MrDoc Official Website Theme Homepage Configuration Guide

MrDoc provides a highly customizable "Official Website Theme Homepage". By configuring a structured JSON object, you can freely build a homepage display similar to a product official website. This document describes each field structure, its function, and usage examples in detail.

---

## 1. Overall Structure of the Configuration File

The Official Website Theme Homepage configuration mainly contains three top-level fields:

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

### Field Description

| Field Name    | Type     | Description                                        |
| ---------- | ------ | ----------------------------------------- |
| **theme**  | string | Theme style identifier, defaults to `"minimal"`, supports `business`, `tech`   |
| **cover**  | object | Configuration for the top cover (large banner) of the homepage                         |
| **blocks** | array  | List of blocks for the main content of the homepage; each block can be of type feature / section, etc. |

---

## 2. cover — Top Cover Configuration

```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"}
    ]
}
```

### Field Description

| Field           | Type     | Description                                             |
| ------------ | ------ | ---------------------------------------------- |
| **title**    | string | Large cover title                                          |
| **subtitle** | string | Description text below the title                                        |
| **bg_theme** | string | Background image for the top cover; options include `minimal`, `green`, `business`, `tech`, `sunset` |
| **ctas**     | array  | Button array (Call to Action)                           |

#### CTA Button Field Description

| Field         | Description                   |
| ---------- | -------------------- |
| **text**   | Button text                 |
| **link**   | Redirect link                 |
| **type**   | Button style type, such as `primary`   |
| **target** | Whether to open in a new window, usually `_blank` |

---

## 3. blocks — Main Content Block Configuration of the Homepage

`blocks` is an array; each block is a module that can display different content.

Currently, two types of modules are supported:

1. **feature** module: used to display a set of icon + title + description
2. **section** module: left-right layout content section with a large image and buttons
3. **project** module: displays a project list in the form of `feature`

These are described separately below.

---

### 3.1 feature Module (Icon Feature Display)

#### Example:

```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"
}
```

#### Field Description

| Field           | Type        | Description                                                              |
| ------------ | --------- | --------------------------------------------------------------- |
| **type**     | "feature" | Fixed as feature                                                     |
| **title**    | string    | Module main title                                                           |
| **subtitle** | string    | Module description (optional)                                                        |
| **contents** | array     | Icon feature array                                                          |
| **bg_color** | string    | Background style, optional (examples: `bg-light`, `bg-light-gradient`, `bg-dark-gradient`) |

#### contents (Feature Item) Field Description

| Field        | Description                |
| --------- | ----------------- |
| **title** | Feature title              |
| **desc**  | Content description              |
| **icon**  | Icon URL (SVG or PNG) |

---

### 3.2 section Module (Left-Right Image-Text Layout)

Suitable for displaying product modules, feature descriptions, promotional introductions, etc.

#### Example

```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"
        }
    ]
}
```

#### Field Description (Items within section → contents)

| Field           | Description                                    |
| ------------ | ------------------------------------- |
| **title**    | Section title                                  |
| **desc**     | Section description; can contain longer content                         |
| **img**      | Large image on the right or left                              |
| **align**    | Image-text layout direction<br/>`left`: image on the left<br/>`right`: image on the right |
| **btns**     | Button list, optional                               |
| **bg_color** | Background color, optional                                |

#### btns Field Description

| Field       | Description   |
| -------- | ---- |
| **text** | Button text |
| **url**  | Redirect link |

### 3.3 project Module (Project List Display)

Suitable for displaying specified projects

#### Example

```
{
    "type": "project",
    "title": "All Projects",
    "subtitle":"This is a project block with the latest documents",
    "contents": [
        {"remark": "First project","id": "4",},
        {"remark": "Second project","id": "13",},
        {"remark": "Second project","id": "13",},
        {"remark": "Second project","id": "13",},
        {"remark": "Second project","id": "13",},
    ],
    "bg_color": "bg-dark-gradient"
},
{
    "type": "project_desc",
    "title": "All Projects",
    "subtitle":"This is a project block with project descriptions",
    "contents": [
        {"remark": "First project","id": "4",},
        {"remark": "Second project","id": "13",},
        {"remark": "Second project","id": "13",},
        {"remark": "Second project","id": "13",},
        {"remark": "Second project","id": "13",},
    ],
    "bg_color": "bg-dark-gradient"
},
```

#### Field Description

| Field           | Type        | Description                                                              |
| ------------ | --------- | --------------------------------------------------------------- |
| **type**     | string | project or project_desc                                                     |
| **title**    | string    | Module main title                                                           |
| **subtitle** | string    | Module description (optional)                                                        |
| **contents** | array     | Project list array                                                          |
| **bg_color** | string    | Background style, optional (examples: `bg-light`, `bg-light-gradient`, `bg-dark-gradient`) |

#### contents (Project) Field Description

| Field        | Description                |
| --------- | ----------------- |
| **remark** | Remark; will not be displayed on the web page              |
| **id**  | Project ID              |

---

## 4. More Configurable Content Examples

### 4.1 Use Cases

Use the feature module to display different use cases:

```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?

Icons can be omitted, with mostly descriptive text:

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

### 4.3 Editions & Services

This also uses the feature module, but feature items support buttons:

```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. How to Start Writing the Homepage Configuration

### Step 1: Edit the Configuration Data

The Official Website Theme Homepage configuration uses the JSON data format. It is recommended to edit it in a code editor or an online JSON formatting website, such as VSCode or https://www.sojson.com/

### Step 2: Fill It In in the Admin Panel

After editing the configuration data, in Admin - Site Settings - Homepage Template, select "Official Website Theme", and then fill the configuration data into the text box below.

### Step 3: Save and Refresh the Homepage

After clicking save, the system will automatically render the template according to the configuration.

---

## 6. Tips and Suggestions

### ✔ It is recommended to use SVG for icons

Clear, lightweight, and able to maintain a consistent effect on dark backgrounds.

### ✔ It is recommended to alternate `align` left and right

This makes the page visually more rhythmic.

### ✔ Background color `bg_color` can be used alternately

For example: `bg-light`, `bg-dark-gradient`, `bg-muted-gradient`
This can improve contrast and reading experience.

---

## 7. Complete Minimal Example (Copyable)

```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"}
            ]
        }
    ]
}
```