### Quick Start Halo with Docker

Source: https://github.com/halo-dev/halo/blob/main/README.md

Use this command to quickly start a Halo experience environment if you have Docker installed. This command maps port 8090 and mounts a local directory for data persistence.

```bash
docker run -d --name halo -p 8090:8090 -v ~/.halo2:/root/.halo2 halohub/halo:2.23
```

--------------------------------

### Get Plugins

Source: https://context7.com/halo-dev/halo/llms.txt

Retrieves a list of installed plugins.

```APIDOC
## GET /apis/plugin.halo.run/v1alpha1/plugins

### Description
Retrieves a list of installed plugins.

### Method
GET

### Endpoint
/apis/plugin.halo.run/v1alpha1/plugins

### Response
#### Success Response (200)
- **items** (array) - A list of plugin objects.
```

--------------------------------

### Install API Client in Plugin

Source: https://github.com/halo-dev/halo/blob/main/ui/packages/api-client/README.md

Install the @halo-dev/api-client and axios packages using pnpm. This is required for using the API client within a Halo plugin.

```shell
pnpm install @halo-dev/api-client axios
```

--------------------------------

### Halo REST API Example - Curl

Source: https://context7.com/halo-dev/halo/llms.txt

Demonstrates common REST API endpoint calls using curl. This is a placeholder for actual API examples.

```bash

```

--------------------------------

### Full-Text Search API Endpoint Example

Source: https://github.com/halo-dev/halo/blob/main/docs/full-text-search/README.md

This example demonstrates how to query for articles using the full-text search API. It includes parameters for keyword, sorting, offset, and limit. Note that the API does not directly support pagination but allows setting a limit for results per query.

```bash
http://localhost:8090/apis/api.halo.run/v1alpha1/posts?keyword=halo&sort=title.asc&sort=publishTimestamp,desc&offset=20&limit=10
```

--------------------------------

### Create PAT Response Example

Source: https://github.com/halo-dev/halo/blob/main/docs/authentication/README.md

This JSON object is an example of a successful response when creating a Personal Access Token (PAT). It includes the PAT's metadata, spec, and the generated access token.

```json
{
  "spec": {
    "description": "This is my first PAT.",
    "expiresAt": "2023-09-16T02:42:35.136Z",
    "roles": [],
    "username": "admin",
    "revoked": false,
    "tokenId": "0b897d9c-56d7-5541-2662-110b70e3f9fd"
  },
  "apiVersion": "security.halo.run/v1alpha1",
  "kind": "PersonalAccessToken",
  "metadata": {
    "generateName": "pat-admin-",
    "name": "pat-admin-lobkm",
    "annotations": {
      "security.halo.run/access-token": "pat_eyJraWQiOiJabUNtcWhJX2FuaFlWQW5aRlVTS0lOckxXRFhqaEp1Nk9ZRGRtcW13Rno4IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJhZG1pbiIsInJvbGVzIjpbXSwicGF0X25hbWUiOiJwYXQtYWRtaW4tbG9ia20iLCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwOTAvIiwiZXhwIjoxNjk0ODMyMTU1LCJpYXQiOjE2OTQ3NDcyOTgsImp0aSI6IjBiODk3ZDljLTU2ZDctNTU0MS0yNjYyLTExMGI3MGUzZjlmZCJ9.UVFYzKmz3bUk7fV6xh_CpuNJA-BR8bci-DIJ7o0fk-hayHXFHr_-7HMrVn7iZcphryqmk0RLv7Zsu_AjY9Qn9iCYybBJBycU0tUJzhDexRtj1ViJtlsraoYxLNSYpJK1hcPngeJuiMa9FZrYGp0k_7GX1NddoXLUBI9orN9DbdKmmJXtvigaxPCp52Mu7fBtVsTmO5fk_y2CglqRl_tkLRpFSgUbERKOqKItctDFRg-WUALBYEpXbhZIXBMuTCsJwhniBMpc1Uu_a1Dqa3K5hDgfHTeUADY2BuhEdYJCODPCzmdfWMNqxYSKQT5JFYoDv-ed6cRqNjKeNvd1IPT3RDkVt_fbo8KPrzvkgIjIzni-Wlwe-pXXQbj_n8iax-jkeK526iu8q2CLptxYxLGD0j8htKZramrov4UkK_eIsotEZZfqig9sYVU5_b442WhOWatdB_pbKj7h-YK1Cb2ueg5kl73bcbBu63b8edJZClp6xr72az343SfBZdwrT_JJ5HR0hJmckAMR_U4qvGWrJ-dobXDgY9Oz-qObfiyglzn0Wrz4HRPlmqDFr2o6TMV7UVjQiV77tDzaNbaXVevXGPS5MaZr313dia7XLpIV3QopXma7rDR6Xnqg7ftDQb5vAvsjwN-JsVabAsdFeCo6ejE1slAD9ZQrD88kgfAIuX4"
    },
    "version": 0,
    "creationTimestamp": "2023-09-15T03:08:18.875350Z"
  }
}
```

--------------------------------

### Backup Configuration Example

Source: https://github.com/halo-dev/halo/blob/main/docs/backup-and-restore.md

This YAML snippet shows a potential configuration for backup compression formats. It specifies options for both extensions data and the work directory.

```yaml
compressions:
  extensions: json | others
  workdir: zip | others
```

--------------------------------

### Example PAT Structure

Source: https://github.com/halo-dev/halo/blob/main/docs/authentication/README.md

PATs in Halo start with 'pat_' followed by a random string, which can be a JWT, UUID, or other encrypted random string. This example shows the 'pat_' prefix combined with a JWT.

```text
pat_eyJraWQiOiJabUNtcWhJX2FuaFlWQW5aRlVTS0lOckxXRFhqaEp1Nk9ZRGRtcW13Rno4IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJhZG1pbiIsInJvbGVzIjpbInN1cGVyLXJvbGUiXSwicGF0X25hbWUiOiJwYXQtYWRtaW4tSVdvbFEiLCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwOTAvIiwiZXhwIjoxNjk0NjcyMDc5LCJpYXQiOjE2OTQ1ODU3MjAsImp0aSI6IjE3ZWFkNzlkLTRkMjctYjg4NS02YjAzLTM4Y2JlYzQxMmFlMyJ9.xiq36NZIM3_ynBx-l0scGdfX-89aJi6uV7HJz_kNnuT78CFmxD-XTpncK1E-hqPdQSrSwyG4gT1pVO17UmUCoyoAkZKKKVk_seFwxdbygIueo2UJA5kVw1Naf_6iLtNkAXxAiYUpd8ihIwvVedhmOMQ9UUfd4QKZDR1XnTW4EAteWBi7b0pWqSa4h5lv7TpmAECY_KDAGrBRGGhc9AxsrGYPNZo68n2QGJ5BjH29vfdQaZz4vwsgKxG1WJ9Y7c8cQI9JN8EyQD_n560NWAaoFnRi1qL3nexvhjq8EVyGVyM48aKA02UcyvI9cxZFk6ZgnzmUsMjyA6ZL7wuexkujVqmc3iO5plBDCjW7oMe1zPQq-gEJXJU6gdr_SHcGG1BjamoekCkOeNT3CPzA_-5j3AVlj7FTFQkbn_h-kV07mfNO45BVVKsMb08HrN6iEk7TOX7SxN0s2gFc3xYVcXBMveLtftOfXs04SvSFCfTDeJH_Jy-3lYb_GLOji7xSc6FgRbuAwmzHLlsgBT4NJhR_0dZ-jNsCDIQCIC3iDc0qbcNTJYYocT77YaQzIkleFIXyPiV0RsNPmSTEDGiDlctsZ-AmcGCDQ-UmW8SIFBrA93OHncvb47o0-uBwZLdF_we4S90hJlNiAPVhhrBMtCoTJotyrODMEzwbLIukvewFXp8
```

--------------------------------

### Backup CRD Example (Succeeded)

Source: https://github.com/halo-dev/halo/blob/main/docs/backup-and-restore.md

This YAML defines a successful Backup custom resource. It specifies the backup format and an auto-delete timestamp. The status indicates successful completion with start and end times, filename, and size.

```yaml
apiVersion: migration.halo.run/v1alpha1
kind: Backup
metadata:
  name: halo-full-backup-xyz
  creationTimestamp: 2023.07.04-10:25:30
spec:
  format: zip
  autoDeleteWhen: 2023.07.10-00:00:00Z
status:
  phase: Succeeded
  startTimestamp: 2023.07.04-10:25:31
  completionTimestamp: 2023.07.04-10:26:30
  filename: halo-full-backup-2023-07-04-10-25-30.zip
  size: 1024 # data unit: bytes
```

--------------------------------

### ReactiveExtensionClient - Post Management

Source: https://context7.com/halo-dev/halo/llms.txt

Demonstrates how to use ReactiveExtensionClient for managing 'Post' resources, including getting, creating, updating, deleting, listing with pagination, filtering, and watching for changes.

```APIDOC
## ReactiveExtensionClient - Post Management

### Description
This section illustrates the usage of `ReactiveExtensionClient` for performing CRUD operations on `Post` resources. It covers fetching individual posts, creating new ones, updating existing posts, deleting posts, listing posts with pagination, and filtering posts based on criteria.

### Methods and Endpoints (Conceptual)

- **Get Post**: Retrieves a single post by its name.
- **Create Post**: Creates a new post.
- **Update Post**: Updates an existing post.
- **Delete Post**: Deletes a post.
- **List Posts**: Retrieves a paginated list of posts.
- **List Published Posts**: Retrieves a stream of published posts, ordered by creation time.
- **Watch Posts**: Sets up a listener to observe real-time changes (add, update, delete) to posts.

### Code Examples (Java)

```java
import run.halo.app.extension.ReactiveExtensionClient;
import run.halo.app.extension.ListOptions;
import run.halo.app.extension.PageRequest;
import run.halo.app.extension.PageRequestImpl;
import run.halo.app.core.extension.content.Post;
import org.springframework.stereotype.Service;
import reactor.core.publisher.Mono;
import reactor.core.publisher.Flux;

@Service
public class PostManagementService {

    private final ReactiveExtensionClient client;

    public PostManagementService(ReactiveExtensionClient client) {
        this.client = client;
    }

    // 获取单篇文章
    public Mono<Post> getPost(String name) {
        return client.get(Post.class, name);
    }

    // 创建文章
    public Mono<Post> createPost(Post post) {
        return client.create(post);
    }

    // 更新文章
    public Mono<Post> updatePost(Post post) {
        return client.update(post);
    }

    // 删除文章
    public Mono<Post> deletePost(Post post) {
        return client.delete(post);
    }

    // 分页查询文章
    public Mono<ListResult<Post>> listPosts(int page, int size) {
        ListOptions options = new ListOptions();
        PageRequest pageRequest = PageRequestImpl.of(page, size);
        return client.listBy(Post.class, options, pageRequest);
    }

    // 使用过滤器和排序器查询
    public Flux<Post> listPublishedPosts() {
        return client.list(Post.class,
            post -> Post.isPublished(post.getMetadata()),
            (p1, p2) -> p2.getMetadata().getCreationTimestamp()
                .compareTo(p1.getMetadata().getCreationTimestamp()));
    }

    // 监听资源变化
    public void watchPosts() {
        client.watch(new Watcher() {
            @Override
            public void onAdd(Extension extension) {
                System.out.println("Post added: " + extension.getMetadata().getName());
            }

            @Override
            public void onUpdate(Extension oldExt, Extension newExt) {
                System.out.println("Post updated: " + newExt.getMetadata().getName());
            }

            @Override
            public void onDelete(Extension extension) {
                System.out.println("Post deleted: " + extension.getMetadata().getName());
            }
        });
    }
}
```
```

--------------------------------

### Table Extension Floating Menu Example

Source: https://github.com/halo-dev/halo/blob/main/ui/packages/editor/docs/extension.md

Example of implementing `getBubbleMenu` for the Table extension to add a column before the current one. It specifies the plugin key, display condition, render container, and the menu item with its icon and action.

```typescript
addOptions() {
  return {
    ...this.parent?.(),
      getBubbleMenu({ editor }) {
        return {
          pluginKey: "tableBubbleMenu",
          shouldShow: ({ state }: { state: EditorState }): boolean => {
            return isActive(state, Table.name);
          },
          getRenderContainer(node) {
            let container = node;
            if (container.nodeName === "#text") {
              container = node.parentElement as HTMLElement;
            }
            while (
              container &&
              container.classList &&
              !container.classList.contains("tableWrapper")
            ) {
              container = container.parentElement as HTMLElement;
            }
            return container;
          },
          tippyOptions: {
            offset: [26, 0],
          },
          items: [
            {
              priority: 10,
              props: {
                icon: markRaw(MdiTableColumnPlusBefore),
                title: i18n.global.t("editor.menus.table.add_column_before"),
                action: () => editor.chain().focus().addColumnBefore().run(),
              },
            },
          ]
        }
      }
  }
}
```

--------------------------------

### Plugin Installation Tab Extension Point Type

Source: https://github.com/halo-dev/halo/blob/main/ui/docs/extension-points/plugin-installation-tabs.md

Defines the type for the `plugin:installation:tabs:create` extension point, specifying that it can return either an array of `PluginInstallationTab` or a Promise resolving to it.

```typescript
"plugin:installation:tabs:create"?: () =>
  | PluginInstallationTab[]
  | Promise<PluginInstallationTab[]>;

```

--------------------------------

### Get Plugin List with cURL

Source: https://context7.com/halo-dev/halo/llms.txt

Retrieves a list of all available plugins. Requires authentication.

```bash
curl -X GET "${BASE_URL}/apis/plugin.halo.run/v1alpha1/plugins" \
  -u "${AUTH}" \
  -H "Content-Type: application/json"
```

--------------------------------

### FormKit List Data Example

Source: https://github.com/halo-dev/halo/blob/main/ui/docs/custom-formkit-input/README.md

Example of the data structure produced by the FormKit 'list' component, showing an array of simple string values.

```json
{
  "users": [
    "Jack",
    "John"
  ]
}
```

--------------------------------

### Custom Menu Group Example

Source: https://github.com/halo-dev/halo/blob/main/ui/docs/routes-generation/README.md

Example of defining a custom menu group for a route, allowing plugins to organize menus under their own categories.

```typescript
{
  name: "帖子",
  group: "社区",
  icon: markRaw(IconCummunity),
  priority: 1,
  mobile: false,
}
```

--------------------------------

### Create PAT Request Example

Source: https://github.com/halo-dev/halo/blob/main/docs/authentication/README.md

This shell command demonstrates how to create a new Personal Access Token (PAT) using a POST request to the specified API endpoint. It includes authentication and a JSON payload with PAT details.

```shell
curl -u admin:admin -X 'POST' \
  'http://localhost:8090/apis/api.console.security.halo.run/v1alpha1/users/-/personalaccesstokens' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "spec": {
    "name": "My PAT",
    "description": "This is my first PAT.",
    "expiresAt": "2023-09-15T02:42:35.136Z"
    "roles": [""]
  }
}'
```

--------------------------------

### Get Themes

Source: https://context7.com/halo-dev/halo/llms.txt

Retrieves a list of available themes.

```APIDOC
## GET /apis/theme.halo.run/v1alpha1/themes

### Description
Retrieves a list of available themes.

### Method
GET

### Endpoint
/apis/theme.halo.run/v1alpha1/themes

### Response
#### Success Response (200)
- **items** (array) - A list of theme objects.
```

--------------------------------

### Create Backup API Request

Source: https://github.com/halo-dev/halo/blob/main/docs/backup-and-restore.md

This is an example of an HTTP POST request to create a backup. It specifies the API endpoint and the content type.

```http
POST /apis/migration.halo.run/v1alpha1/backups
Content-Type: application/json
```

--------------------------------

### Vue Editor Component Example

Source: https://github.com/halo-dev/halo/blob/main/ui/docs/extension-points/editor.md

A Vue component example demonstrating how to bind raw input and content using `v-model:raw` and `v-model:content`. It uses the `marked` library to convert raw markdown to HTML.

```vue
<template>
  <div>
    <textarea :value="raw" @input="onRawUpdate" />
    <div v-html="content" />
  </div>
</template>

<script lang="ts" setup>
import { watch } from "vue";
import marked from "marked";

const props = withDefaults(
  defineProps<{
    raw?: string;
    content: string;
  }>(),
  {
    raw: "",
    content: "",
  }
);

const emit = defineEmits<{
  (event: "update:raw", value: string): void;
  (event: "update:content", value: string): void;
}>();

function onRawUpdate(e: Event) {
  const raw = (e.target as HTMLTextAreaElement).value;
  emit("update:raw", raw);
}

watch(
  () => props.raw,
  () => {
    emit("update:content", marked(props.raw));
  }
);
</script>
```

--------------------------------

### Get Theme List with cURL

Source: https://context7.com/halo-dev/halo/llms.txt

Retrieves a list of all available themes. Requires authentication.

```bash
curl -X GET "${BASE_URL}/apis/theme.halo.run/v1alpha1/themes" \
  -u "${AUTH}" \
  -H "Content-Type: application/json"
```

--------------------------------

### Index Structure Example for Attachments

Source: https://github.com/halo-dev/halo/blob/main/docs/index/README.md

Defines the structure for an index, mapping a key space to index information. It includes functions to generate index keys, specify sort order, and indicate uniqueness. The `ready` flag indicates if the index construction is complete.

```javascript
{
 "/registry/storage.halo.run/groups": [ {
  name: "specName",
  spec: {
    // a function that returns the value of the index key
    indexFunc: function(doc) {
      return doc.spec.name;
    },
    order: 'asc',
    unique: false
  },
  v: 1,
  ready: false
 },
 {
  name: "metadata.labels",
  spec: {
    indexFunc: function(doc) {
       var labels = obj.getMetadata().getLabels();
        if (labels == null) {
          return Set.of();
        }
        return labels.entrySet()
          .stream()
          .map(entry -> entry.getKey() + "=" + entry.getValue())
          .collect(Collectors.toSet());
    },
    order: 'asc',
    unique: false
  },
  v: 1,
  ready: true,
 }]
}
```

--------------------------------

### Restore API Request (Multipart)

Source: https://github.com/halo-dev/halo/blob/main/docs/backup-and-restore.md

This is an example of an HTTP POST request for restoring data using multipart/form-data. It shows how to upload a backup file named 'halo-full-backup.zip'.

```http
POST /apis/migration.halo.run/v1alpha1/restorations
Content-Type: multipart/form-data; boundary="boundary"

'''
--boundary
Content-Disposition: form-data; name="backupfile"; filename="halo-full-backup.zip"
Content-Type: application/zip
'''
```

--------------------------------

### PluginInstallationTab Interface Definition

Source: https://github.com/halo-dev/halo/blob/main/ui/docs/extension-points/plugin-installation-tabs.md

Defines the structure for a plugin installation tab, including its unique identifier, display label, the component to render, optional props, permissions, and priority.

```typescript
export interface PluginInstallationTab {
  id: string;                         // 选项卡的唯一标识
  label: string;                      // 选项卡的名称
  component: Raw<Component>;          // 选项卡面板的组件
  props?: Record<string, unknown>;    // 选项卡组件的 props
  permissions?: string[];             // 权限
  priority: number;                   // 优先级
}

```

--------------------------------

### Backup CRD Example (Failed)

Source: https://github.com/halo-dev/halo/blob/main/docs/backup-and-restore.md

This YAML defines a failed Backup custom resource. It includes compression format options and indicates a failed status with a reason and a human-readable failure message.

```yaml
apiVersion: migration.halo.run/v1alpha1
kind: Backup
metadata:
  name: halo-full-backup-xyz
  creationTimestamp: 2023.07.04-10:25:30
spec:
  compressionFormat: zip | 7z | tar | tar.gz # 压缩格式
status:
  startTimestamp: 2023.07.04-10:25:31
  # Pending: 刚刚创建好 Backup 资源，等待 Reconciler reconcile。
  # Running: Reconciler 正在备份 Halo。
  # Succeeded: Reconciler 成功执行备份 Halo 操作。
  # Failed: 备份 Halo 失败。
  phase: Failed
  failureReason: DatabaseConnectionReset | UnsupportedCompression # 机器可识别的信息
  failureMessage: The database connection reset. # 人类可阅读的信息
```

--------------------------------

### Define GitHub Download Plugin Tab

Source: https://github.com/halo-dev/halo/blob/main/ui/docs/extension-points/plugin-installation-tabs.md

This snippet demonstrates how to define a new tab for the plugin installation interface to support downloading plugins from GitHub. It uses the `definePlugin` function and registers a custom Vue component for the tab. Ensure the `GitHubDownloadTab.vue` component is correctly imported and defined.

```typescript
import { definePlugin } from "@halo-dev/ui-shared";
import { markRaw } from "vue";
import GitHubDownloadTab from "./components/GitHubDownloadTab.vue";

export default definePlugin({
  extensionPoints: {
    "plugin:installation:tabs:create": () => {
      return [
        {
          id: "github",
          label: "GitHub",
          component: markRaw(GitHubDownloadTab),
          props: {
            foo: "bar",
          },
          priority: 30,
        },
      ];
    },
  },
});
```

--------------------------------

### Example Index Data Structure

Source: https://github.com/halo-dev/halo/blob/main/docs/index/README.md

Illustrates the JSON representation of an index, showing how different index names map to values and the associated metadata names. This structure is used to store and retrieve indexed data efficiently.

```json
{
  "metadata.name": {
    "group-1": []
  },
  "specName": {
    "zhangsan": [
        "metadata-name-1"
    ],
    "lisi": [
        "metadata-name-2"
    ]
  },
  "halo.run/hidden": {
    "true": [
        "metadata-name-3"
    ],
    "false": [
        "metadata-name-4"
    ]
  }
}
```

--------------------------------

### Extend Toolbox Items

Source: https://github.com/halo-dev/halo/blob/main/ui/packages/editor/docs/extension.md

Example of how to extend the editor's toolbox by defining the `getToolboxItems` function within a Tiptap Extension's `addOptions` method. This function returns configurations for toolbox items.

```javascript
{
  addOptions() {
    return {
      ...this.parent?.(),
      getToolboxItems({ editor }: { editor: Editor }) {
        return []
      },
    };
  },
}
```

--------------------------------

### Create Backup

Source: https://context7.com/halo-dev/halo/llms.txt

Creates a backup of the Halo instance.

```APIDOC
## POST /apis/migration.halo.run/v1alpha1/backups

### Description
Creates a backup of the Halo instance.

### Method
POST

### Endpoint
/apis/migration.halo.run/v1alpha1/backups

#### Request Body
- **apiVersion** (string) - Required - The API version.
- **kind** (string) - Required - The resource kind.
- **metadata** (object) - Required - Metadata for the backup.
  - **generateName** (string) - Required - A prefix for the backup name.
- **spec** (object) - Required - Specification for the backup.
  - **format** (string) - Required - The format of the backup (e.g., "zip").

### Request Example
```json
{
  "apiVersion": "migration.halo.run/v1alpha1",
  "kind": "Backup",
  "metadata": {
    "generateName": "halo-backup-"
  },
  "spec": {
    "format": "zip"
  }
}
```

### Response
#### Success Response (200)
- **metadata** (object) - Metadata of the created backup.
- **spec** (object) - Specification of the created backup.
```

--------------------------------

### FormKit Repeater Data Example

Source: https://github.com/halo-dev/halo/blob/main/ui/docs/custom-formkit-input/README.md

Example of the data structure produced by the FormKit 'repeater' component, showing an array of objects, each with defined fields.

```json
[
  {
    "full_name": "Jack",
    "email": "jack@example.com"
  },
  {
    "full_name": "John",
    "email": "john@example.com"
  }
]
```

--------------------------------

### Restore from Backup

Source: https://github.com/halo-dev/halo/blob/main/docs/backup-and-restore.md

Restores the Halo site from a previously created backup file. This operation should only be performed when the blog has not been initialized to prevent data inconsistency.

```APIDOC
## POST /apis/migration.halo.run/v1alpha1/restorations

### Description
Restores the Halo site using a provided backup file. This operation is intended for use before the initial blog setup or with caution, as it may overwrite existing data.

### Method
POST

### Endpoint
/apis/migration.halo.run/v1alpha1/restorations

### Parameters
#### Request Body
- **backupfile** (file) - Required - The backup file (e.g., a zip archive) to restore from.

### Request Example
```text
POST /apis/migration.halo.run/v1alpha1/restorations
Content-Type: multipart/form-data; boundary="boundary"

--boundary
Content-Disposition: form-data; name="backupfile"; filename="halo-full-backup.zip"
Content-Type: application/zip

[binary content of the zip file]
--boundary--
```

### Response
#### Success Response (200 or 201)
- **Status Message** (string) - A message indicating the successful initiation or completion of the restore process.

#### Response Example
```text
Restore process initiated successfully.
```
```

--------------------------------

### Create Backup with cURL

Source: https://context7.com/halo-dev/halo/llms.txt

Creates a new backup of the Halo instance. Requires authentication and specifies the backup format.

```bash
curl -X POST "${BASE_URL}/apis/migration.halo.run/v1alpha1/backups" \
  -u "${AUTH}" \
  -H "Content-Type: application/json" \
  -d '{
    "apiVersion": "migration.halo.run/v1alpha1",
    "kind": "Backup",
    "metadata": {
      "generateName": "halo-backup-"
    },
    "spec": {
      "format": "zip"
    }
  }'
```

--------------------------------

### 实现后置过滤器

Source: https://github.com/halo-dev/halo/blob/main/docs/extension-points/authentication.md

实现 `AfterSecurityWebFilter` 接口，在认证后执行自定义逻辑。在此过滤器中，可以通过 `ReactiveSecurityContextHolder` 获取 `SecurityContext`。

```java
public class MyAfterSecurityWebFilter implements AfterSecurityWebFilter {

  @Override
  public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
    return ReactiveSecurityContextHolder.getContext()
            .switchIfEmpty(Mono.defer(() -> {
              // do something...
              return chain.filter(exchange).then(Mono.empty());
            }))
            .flatMap(securityContext -> {
              // do something...
              return chain.filter(exchange);
            });
  }
}
```

--------------------------------

### Get Users

Source: https://context7.com/halo-dev/halo/llms.txt

Retrieves a list of users.

```APIDOC
## GET /apis/api.console.halo.run/v1alpha1/users

### Description
Retrieves a list of users.

### Method
GET

### Endpoint
/apis/api.console.halo.run/v1alpha1/users

### Response
#### Success Response (200)
- **items** (array) - A list of user objects.
```

--------------------------------

### 实现内容扩展点（Katex 公式渲染）

Source: https://context7.com/halo-dev/halo/llms.txt

通过实现 ReactivePostContentHandler 接口，在文章渲染前修改内容。此示例检测内容是否包含数学公式标记，并注入 Katex 渲染脚本。

```java
import run.halo.app.theme.ReactivePostContentHandler;
import org.springframework.stereotype.Component;
import reactor.core.publisher.Mono;

@Component
public class KatexContentHandler implements ReactivePostContentHandler {

    private static final String KATEX_SCRIPT = """
        <link rel="stylesheet" href="/plugins/plugin-katex/assets/static/katex.min.css">
        <script defer src="/plugins/plugin-katex/assets/static/katex.min.js"></script>
        <script defer src="/plugins/plugin-katex/assets/static/contrib/auto-render.min.js"></script>
        <script>
            document.addEventListener("DOMContentLoaded", function() {
                renderMathInElement(document.body, {
                    delimiters: [
                        {left: '$$', right: '$$', display: true},
                        {left: '$', right: '$', display: false}
                    ],
                    throwOnError: false
                });
            });
        </script>
        """;

    @Override
    public Mono<PostContentContext> handle(PostContentContext context) {
        String content = context.getContent();
        // 检测是否包含数学公式
        if (content.contains("$") || content.contains("\\[")) {
            context.setContent(KATEX_SCRIPT + "\n" + content);
        }
        return Mono.just(context);
    }
}
```

--------------------------------

### Create Backup

Source: https://github.com/halo-dev/halo/blob/main/docs/backup-and-restore.md

Initiates a full backup of the Halo site. This operation is asynchronous and creates a Backup custom resource to track the process.

```APIDOC
## POST /apis/migration.halo.run/v1alpha1/backups

### Description
Initiates a full backup of the Halo site, including database and work directory data. The backup process is asynchronous and its status is tracked via a custom resource.

### Method
POST

### Endpoint
/apis/migration.halo.run/v1alpha1/backups

### Parameters
#### Request Body
This endpoint does not explicitly define a request body schema in the provided text, but it is expected to trigger the backup creation process.

### Request Example
```text
POST /apis/migration.halo.run/v1alpha1/backups
Content-Type: application/json
```

### Response
#### Success Response (200 or 201)
- **Backup Resource** (object) - The created Backup custom resource, reflecting the initial state of the backup request.

#### Response Example
```yaml
apiVersion: migration.halo.run/v1alpha1
kind: Backup
metadata:
  name: halo-full-backup-xyz
  creationTimestamp: 2023.07.04-10:25:30
spec:
  format: zip
  autoDeleteWhen: 2023.07.10-00:00:00Z
status:
  phase: Pending
  startTimestamp: 2023.07.04-10:25:31
```
```

--------------------------------

### 实现表单登录认证扩展

Source: https://context7.com/halo-dev/halo/llms.txt

通过实现 FormLoginSecurityWebFilter 接口来扩展表单登录认证逻辑。可在此处添加自定义的登录处理，例如特殊管理员账号的识别。

```java
import run.halo.app.security.FormLoginSecurityWebFilter;
import org.springframework.web.server.ServerWebExchange;
import org.springframework.web.server.WebFilterChain;
import org.springframework.stereotype.Component;
import reactor.core.publisher.Mono;

// 表单登录认证扩展
@Component
public class MyFormLoginFilter implements FormLoginSecurityWebFilter {
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
        // 自定义表单登录逻辑
        String username = exchange.getRequest()
            .getQueryParams().getFirst("username");
        if (username != null && username.startsWith("admin_")) {
            // 特殊处理管理员登录
        }
        return chain.filter(exchange);
    }
}
```

--------------------------------

### Get Single Post

Source: https://context7.com/halo-dev/halo/llms.txt

Retrieves a specific post by its slug.

```APIDOC
## GET /apis/content.halo.run/v1alpha1/posts/{slug}

### Description
Retrieves a specific post by its slug.

### Method
GET

### Endpoint
/apis/content.halo.run/v1alpha1/posts/{slug}

#### Path Parameters
- **slug** (string) - Required - The slug of the post to retrieve.

### Response
#### Success Response (200)
- **apiVersion** (string) - The API version.
- **kind** (string) - The resource kind.
- **metadata** (object) - Metadata of the post.
- **spec** (object) - Specification of the post.

#### Response Example
{
  "apiVersion": "content.halo.run/v1alpha1",
  "kind": "Post",
  "metadata": {
    "name": "my-first-post",
    "creationTimestamp": "2023-10-27T10:00:00Z"
  },
  "spec": {
    "title": "My First Post",
    "slug": "my-first-post",
    "content": "This is the content of my first post.",
    "visible": "PUBLIC"
  }
}
```

--------------------------------

### Halo Frontend Build Artifacts Structure

Source: https://github.com/halo-dev/halo/blob/main/ui/docs/project-structure/README.md

This Bash snippet illustrates the directory structure of the built frontend artifacts for Halo, showing the output of the multi-page build process for Console and User Center.

```bash
build/dist/ui
├── console.html
├── uc.html
└── ui-assets/

```

--------------------------------

### 使用表单登录进行 API 请求 (HTTP 302 响应)

Source: https://github.com/halo-dev/halo/blob/main/docs/authentication/README.md

当 `Accept` 请求头不包含 `application/json` 时，表单登录会返回 HTTP 302 重定向响应。

```bash
curl 'http://localhost:8090/login' \
  -H 'Accept: */*' \
  -H 'Cookie: XSRF-TOKEN=1ff67e0c-6f2c-4cf9-afb5-81bc1015b8e5' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-raw '_csrf=1ff67e0c-6f2c-4cf9-afb5-81bc1015b8e5&username=admin&password=P@88w0rd'
```

--------------------------------

### Get Current User

Source: https://context7.com/halo-dev/halo/llms.txt

Retrieves information about the currently authenticated user.

```APIDOC
## GET /apis/api.console.halo.run/v1alpha1/users/-

### Description
Retrieves information about the currently authenticated user.

### Method
GET

### Endpoint
/apis/api.console.halo.run/v1alpha1/users/-

### Response
#### Success Response (200)
- **username** (string) - The username of the current user.
- **displayName** (string) - The display name of the current user.
```

--------------------------------

### Get Posts

Source: https://context7.com/halo-dev/halo/llms.txt

Retrieves a list of posts. Supports pagination, sorting, and filtering.

```APIDOC
## GET /apis/api.console.halo.run/v1alpha1/posts

### Description
Retrieves a list of posts. Supports pagination, sorting, and filtering.

### Method
GET

### Endpoint
/apis/api.console.halo.run/v1alpha1/posts

#### Query Parameters
- **page** (integer) - Optional - The page number for pagination.
- **size** (integer) - Optional - The number of items per page.
- **sort** (string) - Optional - The sorting order (e.g., `metadata.creationTimestamp,desc`).
- **labelSelector** (string) - Optional - Filters posts based on labels (e.g., `content.halo.run/published=true`).

### Response
#### Success Response (200)
- **items** (array) - A list of post objects.

#### Response Example
{
  "items": [
    {
      "apiVersion": "content.halo.run/v1alpha1",
      "kind": "Post",
      "metadata": {
        "name": "my-first-post",
        "creationTimestamp": "2023-10-27T10:00:00Z"
      },
      "spec": {
        "title": "My First Post",
        "slug": "my-first-post",
        "visible": "PUBLIC"
      }
    }
  ]
}
```

--------------------------------

### Get User List with cURL

Source: https://context7.com/halo-dev/halo/llms.txt

Retrieves a list of all users. Requires authentication.

```bash
curl -X GET "${BASE_URL}/apis/api.console.halo.run/v1alpha1/users" \
  -u "${AUTH}" \
  -H "Content-Type: application/json"
```

--------------------------------

### Get Post List with cURL

Source: https://context7.com/halo-dev/halo/llms.txt

Retrieves a list of all posts. Requires authentication.

```bash
curl -X GET "${BASE_URL}/apis/api.console.halo.run/v1alpha1/posts" \
  -u "${AUTH}" \
  -H "Content-Type: application/json"
```

--------------------------------

### Access WebSocket Endpoint with websocat

Source: https://github.com/halo-dev/halo/blob/main/docs/plugin/websocket.md

This bash command demonstrates how to connect to the WebSocket endpoint exposed by a Halo plugin using `websocat`. It includes basic authentication with default admin credentials. The endpoint is accessible at the specified URL.

```bash
websocat --basic-auth admin:admin ws://127.0.0.1:8090/apis/my-plugin.halowrite.com/v1alpha1/resources
```

--------------------------------

### ReactiveExtensionClient for Simplified Querying

Source: https://github.com/halo-dev/halo/blob/main/docs/index/README.md

Introduces the `ReactiveExtensionClient` and its `listBy` method as a simplified way to query extension data, abstracting the `IndexedQueryEngine`.

```APIDOC
## ReactiveExtensionClient for Simplified Querying

### Description
The `ReactiveExtensionClient` offers a simplified `listBy` method for querying extension data, providing a more convenient interface compared to directly using the `IndexedQueryEngine`.

### Method
Simplified data retrieval method.

### Endpoint
N/A (Interface definition)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```java
public interface ReactiveExtensionClient {
  //...
  <E extends Extension> Mono<ListResult<E>> listBy(Class<E> type, ListOptions options,
        PageRequest pageable);
}
```

### Response
#### Success Response (200)
N/A (Interface definition)

#### Response Example
N/A
```

--------------------------------

### 实现前置过滤器

Source: https://github.com/halo-dev/halo/blob/main/docs/extension-points/authentication.md

实现 `BeforeSecurityWebFilter` 接口，在认证前执行自定义逻辑。注意，此时无法直接通过 `ReactiveSecurityContextHolder` 获取 `SecurityContext`。

```java
public class MyBeforeSecurityWebFilter implements BeforeSecurityWebFilter {

  @Override
  public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
    // Do your logic here
    return chain.filter(exchange);
  }
}
```

--------------------------------

### Get Single Post with cURL

Source: https://context7.com/halo-dev/halo/llms.txt

Retrieves a specific post by its name. Requires authentication.

```bash
curl -X GET "${BASE_URL}/apis/content.halo.run/v1alpha1/posts/my-first-post" \
  -u "${AUTH}" \
  -H "Content-Type: application/json"
```

--------------------------------

### Create Post with cURL

Source: https://context7.com/halo-dev/halo/llms.txt

Creates a new post with specified metadata and content. Requires authentication.

```bash
curl -X POST "${BASE_URL}/apis/content.halo.run/v1alpha1/posts" \
  -u "${AUTH}" \
  -H "Content-Type: application/json" \
  -d '{
    "apiVersion": "content.halo.run/v1alpha1",
    "kind": "Post",
    "metadata": {
      "name": "my-new-post"
    },
    "spec": {
      "title": "我的新文章",
      "slug": "my-new-post",
      "deleted": false,
      "publish": false,
      "pinned": false,
      "allowComment": true,
      "visible": "PUBLIC",
      "priority": 0,
      "excerpt": {
        "autoGenerate": true
      }
    }
  }'
```

--------------------------------

### Algolia Search Parameters

Source: https://github.com/halo-dev/halo/blob/main/docs/full-text-search/README.md

Example of search parameters used with Algolia, including query, attributes, and filtering.

```json
{
            "exhaustiveNbHits": true,
            "exhaustiveTypo": true,
            "exhaustive": {
                "nbHits": true,
                "typo": true
            },
            "query": "halo",
            "params": "query=halo&attributesToRetrieve=%5B%22hierarchy.lvl0%22%2C%22hierarchy.lvl1%22%2C%22hierarchy.lvl2%22%2C%22hierarchy.lvl3%22%2C%22hierarchy.lvl4%22%2C%22hierarchy.lvl5%22%2C%22hierarchy.lvl6%22%2C%22content%22%2C%22type%22%2C%22url%22%5D&attributesToSnippet=%5B%22hierarchy.lvl1%3A5%22%2C%22hierarchy.lvl2%3A5%22%2C%22hierarchy.lvl3%3A5%22%2C%22hierarchy.lvl4%3A5%22%2C%22hierarchy.lvl5%3A5%22%2C%22hierarchy.lvl6%3A5%22%2C%22content%3A5%22%5D&snippetEllipsisText=%E2%80%A6&highlightPreTag=%3Cmark%3E&highlightPostTag=%3C%2Fmark%3E&hitsPerPage=20&facetFilters=%5B%22language%3Azh-Hans%22%2C%5B%22docusaurus_tag%3Adefault%22%2C%22docusaurus_tag%3Adocs-default-1.6%22%5D%5D",
            "index": "docs",
            "renderingContent": {},
            "processingTimeMS": 1,
            "processingTimingsMS": {
                "total": 1
            }
        }
```

--------------------------------

### Manual Index Declaration with IndexSpec

Source: https://github.com/halo-dev/halo/blob/main/docs/index/README.md

Demonstrates how to manually declare indexes for an extension using the IndexSpec class and register them with the IndexSpecRegistry.

```APIDOC
## Manual Index Declaration

### Description
This section describes how to manually define and register indexes for extensions using the `IndexSpec` class.

### Method
Programmatic registration via `IndexSpecRegistry`.

### Endpoint
N/A (Code-based registration)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```java
IndexSpecs indexSpecs = indexSpecRegistry.indexFor(Person.class);
indexSpecs.add(new IndexSpec()
    .setName("spec.name")
    .setOrder(IndexSpec.OrderType.DESC)
    .setIndexFunc(IndexAttributeFactory.simpleAttribute(Person.class,
        e -> e.getSpec().getName()))
    .setUnique(false));
```

### Response
#### Success Response (200)
N/A (This is a code registration process, not an API call)

#### Response Example
N/A
```

--------------------------------

### Get Current User Info with cURL

Source: https://context7.com/halo-dev/halo/llms.txt

Retrieves information about the currently authenticated user. Requires authentication.

```bash
curl -X GET "${BASE_URL}/apis/api.console.halo.run/v1alpha1/users/-" \
  -u "${AUTH}" \
  -H "Content-Type: application/json"
```

--------------------------------

### Example JWT Header for PAT

Source: https://github.com/halo-dev/halo/blob/main/docs/authentication/README.md

This JSON object represents the header of the JWT part of a PAT, specifying the key ID and the signing algorithm used.

```json
{
  "kid": "ZmCmqhI_anhYVAnZFUSKINrLWDXjhJu6OYDdmqmwFz8",
  "alg": "RS256"
}
```

--------------------------------

### 使用表单登录进行 API 请求 (JSON 响应)

Source: https://github.com/halo-dev/halo/blob/main/docs/authentication/README.md

使用 `curl` 发送 POST 请求到 `/login` 端点，提供用户名、密码和 CSRF 令牌，并设置 `Accept: application/json` 请求头，以获取 JSON 格式的登录响应。

```bash
curl 'http://localhost:8090/login' \
  -H 'Accept: application/json' \
  -H 'Cookie: XSRF-TOKEN=1ff67e0c-6f2c-4cf9-afb5-81bc1015b8e5' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-raw '_csrf=1ff67e0c-6f2c-4cf9-afb5-81bc1015b8e5&username=admin&password=P@88w0rd'
```