diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 5aefb63..b099269 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -3,6 +3,13 @@ import { set_sidebar } from "../utils/auto_sidebar.js";
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
+  markdown: {
+    vue: {
+      compilerOptions: {
+        isCustomElement: () => true // 禁止解析 ${{ }}
+      }
+    }
+  } as any,
   title: "devstar",
   head: [['link', { rel: 'icon', href: '/devstar-logo.png' }]],
   description: "A VitePress Site",
@@ -35,6 +42,7 @@ export default defineConfig({
       {
         text: 'devstar是什么',
         link: '/document/index',
+        attrs: { class: 'bold-item' }
       } as any,
       {
         text: '安装',
@@ -58,7 +66,7 @@ export default defineConfig({
       } as any,
       {
         text: '管理',
-        link: 'https://docs.gitea.com/zh-cn/category/administration',
+        // link: 'https://docs.gitea.com/zh-cn/category/administration',
         collapsible: true, // 使整个组可折叠
         collapsed: true, // 默认展开
         items: [
@@ -79,13 +87,14 @@ export default defineConfig({
           { text: 'GPG提交签名', link: '/document/administration/signing.md' },
           { text: '外部渲染器', link: '/document/administration/external-renderers.md' },
           { text: '搜索引擎索引', link: '/document/administration/search-engines-indexation.md' },
-          { text: '自定义Gitea配置', link: '/document/administration/customizing-gitea.md' },
+          // { text: '自定义Gitea配置', link: '/document/administration/customizing-gitea.md' },
+          { text: '自定义Gitea配置', link: 'https://docs.gitea.com/zh-cn/administration/customizing-gitea' },
           { text: '添加法律页面', link: '/document/administration/adding-legal-pages.md' }
         ]
       } as any,
       {
         text: '使用',
-        link: 'https://docs.gitea.com/zh-cn/category/usage',
+        // link: 'https://docs.gitea.com/zh-cn/category/usage',
         collapsible: true, // 使整个组可折叠
         collapsed: true, // 默认展开
         items: [
@@ -94,15 +103,15 @@ export default defineConfig({
             collapsible: true, // 使整个组可折叠
             collapsed: false, // 默认展开
             items: [
-              { text: 'Overview', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: '快速入门', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: '与GitHub Actions的对比', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: 'Act Runner', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: '变量', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: 'Gitea Actions设计', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: '密钥管理', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: 'Gitea Actions常见问题解答', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: 'Badge', link: 'https://docs.gitea.com/zh-cn/installation/comparison' }
+              { text: 'Overview', link: 'document/usage/actions/overview.md' },
+              { text: '快速入门', link: 'document/usage/actions/quickstart.md' },
+              { text: '与GitHub Actions的对比', link: 'document/usage/actions/comparison.md' },
+              { text: 'Act Runner', link: 'document/usage/actions/act-runner.md' },
+              { text: '变量', link: 'document/usage/actions/variables.md' },
+              { text: 'Gitea Actions设计', link: 'document/usage/actions/design.md' },
+              { text: '密钥管理', link: 'document/usage/actions/secrets.md' },
+              { text: 'Gitea Actions常见问题解答', link: 'document/usage/actions/faq.md' },
+              { text: 'Badge', link: 'document/usage/actions/badge.md' }  // 注意：Badge未找到对应文件，暂用comparison.md
             ]
           },
           {
@@ -110,88 +119,115 @@ export default defineConfig({
             collapsible: true, // 使整个组可折叠
             collapsed: true, // 默认展开
             items: [
-              { text: '软件包注册表', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: 'Alpine 软件包注册表', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: 'Arch package registry', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: 'Cargo 软件包注册表', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: 'Chef 软件包注册表', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: '存储', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: 'Composer 软件包注册表', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: 'Conan 软件包注册表', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: 'Conda 软件包注册表', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: '容器注册表', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: 'CRAN 软件包注册表', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: 'Go 软件包注册表', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: 'Helm Chart 注册表', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: 'Maven 软件包注册表', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: 'NPM Package Registry', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: 'NuGet 软件包注册表', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: 'Pub 软件包注册表', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: 'PyPI 软件包注册表', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: 'RPM 软件包注册表', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: 'RubyGems 软件包注册表', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: 'Swift 软件包注册表', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: 'Vagrant 软件包注册表', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: '通用软件包注册表', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-              { text: 'Debian 软件包注册表', link: 'https://docs.gitea.com/zh-cn/installation/comparison' }
+              { text: '软件包注册表', link: '/document/usage/packages/overview.md' },
+              { text: 'Alpine 软件包注册表', link: '/document/usage/packages/alpine.md' },
+              { text: 'Arch package registry', link: '/document/usage/packages/arch.md' },
+              { text: 'Cargo 软件包注册表', link: '/document/usage/packages/cargo.md' },
+              { text: 'Chef 软件包注册表', link: '/document/usage/packages/chef.md' },
+              { text: 'Composer 软件包注册表', link: '/document/usage/packages/composer.md' },
+              { text: 'Conan 软件包注册表', link: '/document/usage/packages/conan.md' },
+              { text: 'Conda 软件包注册表', link: '/document/usage/packages/conda.md' },
+              { text: '容器注册表', link: '/document/usage/packages/container.md' },
+              { text: 'CRAN 软件包注册表', link: '/document/usage/packages/cran.md' },
+              { text: 'Debian 软件包注册表', link: '/document/usage/packages/debian.md' },
+              { text: '通用软件包注册表', link: '/document/usage/packages/generic.md' },
+              { text: 'Go 软件包注册表', link: '/document/usage/packages/go.md' },
+              { text: 'Helm Chart 注册表', link: '/document/usage/packages/helm.md' },
+              { text: 'Maven 软件包注册表', link: '/document/usage/packages/maven.md' },
+              { text: 'NPM Package Registry', link: '/document/usage/packages/npm.md' },
+              { text: 'NuGet 软件包注册表', link: '/document/usage/packages/nuget.md' },
+              { text: 'Pub 软件包注册表', link: '/document/usage/packages/pub.md' },
+              { text: 'PyPI 软件包注册表', link: '/document/usage/packages/pypi.md' },
+              { text: 'RPM 软件包注册表', link: '/document/usage/packages/rpm.md' },
+              { text: 'RubyGems 软件包注册表', link: '/document/usage/packages/rubygems.md' },
+              { text: '存储', link: '/document/usage/packages/storage.md' },
+              { text: 'Swift 软件包注册表', link: '/document/usage/packages/swift.md' },
+              { text: 'Vagrant 软件包注册表', link: '/document/usage/packages/vagrant.md' }
             ]
           },
-          { text: 'AGit', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: '个人资料 README', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: 'Blame File View', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: '邮件接收', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: '标签', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: '合并请求', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: '权限', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: '模板仓库', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: '从模板创建工单与合并请求', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: '自动链接引用', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: '合并消息模板', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: '推送', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: 'Blocking a user', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: '克隆过滤器 (部分克隆)', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: 'Code Owners', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: 'Webhooks', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: 'Migration', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: '受保护的标签', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: '仓库镜像', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: 'Markdown', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: 'Multi-factor Authentication (MFA)', link: 'https://docs.gitea.com/zh-cn/installation/comparison' }
+          { text: 'AGit', link: '/document/usage/agit.md' },
+          { text: '个人资料 README', link: '/document/usage/profile-readme.md' },
+          { text: 'Blame File View', link: '/document/usage/blame.md' },
+          { text: '邮件接收', link: '/document/usage/incoming-email.md' },
+          { text: '标签', link: '/document/usage/labels.md' },
+          { text: '合并请求', link: '/document/usage/pull-request.md' },
+          { text: '权限', link: '/document/usage/permissions.md' },
+          { text: '模板仓库', link: '/document/usage/template-repositories.md' },
+          { text: '从模板创建工单与合并请求', link: '/document/usage/issue-pull-request-templates.md' },
+          { text: '自动链接引用', link: '/document/usage/linked-references.md' },
+          { text: '合并消息模板', link: '/document/usage/merge-message-templates.md' },
+          { text: '推送', link: '/document/usage/push.md' },
+          { text: 'Blocking a user', link: '/document/usage/blocking-users.md' },
+          { text: '克隆过滤器(部分克隆)', link: '/document/usage/clone-filter.md' },
+          { text: 'Code Owners', link: '/document/usage/code-owners.md' },
+          { text: 'Webhooks', link: '/document/usage/webhooks.md' },
+          { text: 'Migration', link: '/document/usage/migration.md' },
+          { text: '受保护的标签', link: '/document/usage/protected-tags.md' },
+          { text: '仓库镜像', link: '/document/usage/repo-mirror.md' },
+          { text: 'Markdown', link: '/document/usage/markdown.md' },
+          { text: 'Multi-factor Authentication (MFA)', link: '/document/usage/multi-factor-authentication.md' }
         ]
       } as any,
       {
         text: '开发',
-        link: 'https://docs.gitea.com/zh-cn/category/development',
+        // link: 'https://docs.gitea.com/zh-cn/category/development',
         collapsible: true, // 使整个组可折叠
         collapsed: true, // 默认展开
         items: [
-          { text: '玩转 Gitea', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: 'API 使用指南', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: 'OAuth2 提供者', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: '迁移接口', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: '集成', link: 'https://docs.gitea.com/zh-cn/installation/comparison' }
+          {
+            text: '玩转 Gitea',
+            link: '/document/development/hacking-on-gitea.md'  // 匹配"API 使用指南"对应的文件名
+          },
+          {
+            text: 'API 使用指南',
+            link: '/document/development/api-usage.md'  // 直接使用文件名
+          },
+          {
+            text: 'OAuth2 提供者',
+            link: '/document/development/oauth2-provider.md'  // 推测文件名
+          },
+          {
+            text: '迁移接口',
+            link: '/document/development/migrations.md'  // 推测文件名
+          },
+          {
+            text: '集成',
+            link: '/document/development/integrations.md'  // 推测文件名
+          }
         ]
       } as any,
       {
         text: '贡献',
-        link: 'https://docs.gitea.com/zh-cn/category/contributing',
+        // link: 'https://docs.gitea.com/zh-cn/category/contributing',
         collapsible: true, // 使整个组可折叠
         collapsed: true, // 默认展开
         items: [
-          { text: '后端开发指南', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: '前端开发指南', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: '重构指南', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: '本地化', link: 'https://docs.gitea.com/zh-cn/installation/comparison' }
+          {
+            text: '后端开发指南',
+            link: '/document/contributing/guidelines-backend.md'  // 匹配文件名：guidelines - backend.md
+          },
+          {
+            text: '前端开发指南',
+            link: '/document/contributing/guidelines-frontend.md'  // 匹配文件名：guidelines - frontend.md
+          },
+          {
+            text: '重构指南',
+            link: '/document/contributing/guidelines-refactoring.md'  // 匹配文件名：guidelines - refactoring.md
+          },
+          {
+            text: '本地化',
+            link: '/document/contributing/localization.md'  // 文件名完全一致
+          }
         ]
       } as any,
       {
         text: '帮助',
-        link: 'https://docs.gitea.com/zh-cn/category/help',
+        // link: 'https://docs.gitea.com/zh-cn/category/help',
         collapsible: true, // 使整个组可折叠
         collapsed: true, // 默认展开
         items: [
-          { text: '常见问题', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
-          { text: '支持选项', link: 'https://docs.gitea.com/zh-cn/installation/comparison' },
+          { text: '常见问题', link: 'document/help/faq.md' },
+          { text: '支持选项', link: 'document/help/support.md' },
         ]
       } as any,
     ],
diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css
new file mode 100644
index 0000000..b1130ac
--- /dev/null
+++ b/docs/.vitepress/theme/custom.css
@@ -0,0 +1,6 @@
+/* .vitepress/theme/custom.css */
+.bold-item {
+  font-weight: 700 !important;
+  font-size: 1em !important;
+  /* 与其他目录项字号一致 */
+}
\ No newline at end of file
diff --git a/docs/document/contributing/guidelines-backend.md b/docs/document/contributing/guidelines-backend.md
new file mode 100644
index 0000000..758e417
--- /dev/null
+++ b/docs/document/contributing/guidelines-backend.md
@@ -0,0 +1,110 @@
+---
+date: "2023-05-25T23:41:00+08:00"
+slug: "guidelines-backend"
+sidebar_position: 20
+aliases:
+  - /zh-cn/guidelines-backend
+---
+
+# 后端开发指南
+
+## 背景
+
+Gitea 使用 Golang 作为后端编程语言。它使用了许多第三方包，并且自己也编写了一些包。
+例如，Gitea 使用[Chi](https://github.com/go-chi/chi)作为基本的 Web 框架。[Xorm](https://xorm.io)是一个用于与数据库交互的 ORM 框架。
+因此，管理这些包非常重要。在开始编写后端代码之前，请参考以下准则。
+
+## 包设计准则
+
+### 包列表
+
+为了保持易于理解的代码并避免循环依赖，拥有良好的代码结构是很重要的。Gitea 后端分为以下几个部分：
+
+- `build`：帮助构建 Gitea 的脚本。
+- `cmd`：包含所有 Gitea 的实际子命令，包括 web、doctor、serv、hooks、admin 等。`web`将启动 Web 服务。`serv`和`hooks`将被 Git 或 OpenSSH 调用。其他子命令可以帮助维护 Gitea。
+- `tests`：常用的测试函数
+- `tests/integration`：集成测试，用于测试后端回归。
+- `tests/e2e`：端到端测试，用于测试前端和后端的兼容性和视觉回归。
+- `models`：包含由 xorm 用于构建数据库表的数据结构。它还包含查询和更新数据库的函数。应避免与其他 Gitea 代码的依赖关系。在某些情况下，比如日志记录时可以例外。
+  - `models/db`：基本的数据库操作。所有其他`models/xxx`包都应依赖于此包。`GetEngine`函数只能从 models/中调用。
+  - `models/fixtures`：单元测试和集成测试中使用的示例数据。一个`yml`文件表示一个将在测试开始时加载到数据库中的表。
+  - `models/migrations`：存储不同版本之间的数据库迁移。修改数据库结构的 PR**必须**包含一个迁移步骤。
+- `modules`：在 Gitea 中处理特定功能的不同模块。工作正在进行中：其中一些模块应该移到`services`中，特别是那些依赖于 models 的模块，因为它们依赖于数据库。
+  - `modules/setting`：存储从 ini 文件中读取的所有系统配置，并在各处引用。但是在可能的情况下，应将其作为函数参数使用。
+  - `modules/git`：用于与`Git`命令行或 Gogit 包交互的包。
+- `public`：编译后的前端文件（JavaScript、图像、CSS 等）
+- `routers`：处理服务器请求。由于它使用其他 Gitea 包来处理请求，因此其他包（models、modules 或 services）不能依赖于 routers。
+  - `routers/api`：包含`/api/v1`相关路由，用于处理 RESTful API 请求。
+  - `routers/install`：只能在系统处于安装模式（INSTALL_LOCK=false）时响应。
+  - `routers/private`：仅由内部子命令调用，特别是`serv`和`hooks`。
+  - `routers/web`：处理来自 Web 浏览器或 Git SMART HTTP 协议的 HTTP 请求。
+- `services`：用于常见路由操作或命令执行的支持函数。使用`models`和`modules`来处理请求。
+- `templates`：用于生成 HTML 输出的 Golang 模板。
+
+### 包依赖关系
+
+由于 Golang 不支持导入循环，我们必须仔细决定包之间的依赖关系。这些包之间有一些级别。以下是理想的包依赖关系方向。
+
+`cmd` -> `routers` -> `services` -> `models` -> `modules`
+
+从左到右，左侧的包可以依赖于右侧的包，但右侧的包不能依赖于左侧的包。在同一级别的子包中，可以根据该级别的规则进行依赖。
+
+**注意事项**
+
+为什么我们需要在`models`之外使用数据库事务？以及如何使用？
+某些操作在数据库记录插入/更新/删除失败时应该允许回滚。
+因此，服务必须能够创建数据库事务。以下是一些示例：
+
+```go
+// services/repository/repository.go
+func CreateXXXX() error {
+    return db.WithTx(func(ctx context.Context) error {
+        // do something, if err is returned, it will rollback automatically
+        if err := issues.UpdateIssue(ctx, repoID); err != nil {
+            // ...
+            return err
+        }
+        // ...
+        return nil
+    })
+}
+```
+
+在`services`中**不应该**直接使用`db.GetEngine(ctx)`，而是应该在`models/`下编写一个函数。
+如果该函数将在事务中使用，请将`context.Context`作为函数的第一个参数。
+
+```go
+// models/issues/issue.go
+func UpdateIssue(ctx context.Context, repoID int64) error {
+    e := db.GetEngine(ctx)
+
+    // ...
+}
+```
+
+### 包名称
+
+对于顶层包，请使用复数作为包名，例如`services`、`models`，对于子包，请使用单数，例如`services/user`、`models/repository`。
+
+### 导入别名
+
+由于有一些使用相同包名的包，例如`modules/user`、`models/user`和`services/user`，当这些包在一个 Go 文件中被导入时，很难知道我们使用的是哪个包以及它是变量名还是导入名。因此，我们始终建议使用导入别名。为了与常见的驼峰命名法的包变量区分开，建议使用**snake_case**作为导入别名的命名规则。
+例如：`import user_service "code.gitea.io/gitea/services/user"`
+
+### 重要注意事项
+
+- 永远不要写成`x.Update(exemplar)`，而没有明确的`WHERE`子句：
+  - 这将导致表中的所有行都被使用 exemplar 的非零值进行更新，包括 ID。
+  - 通常应该写成`x.ID(id).Update(exemplar)`。
+- 如果在迁移过程中使用`x.Insert(exemplar)`向表中插入记录，而 ID 是预设的：
+  - 对于 MSSQL 变体，你将需要执行`` SET IDENTITY_INSERT `table` ON ``（否则迁移将失败）
+  - 对于 PostgreSQL，你还需要更新 ID 序列，否则迁移将悄无声息地通过，但后续的插入将失败：
+    `` SELECT setval('table_name_id_seq', COALESCE((SELECT MAX(id)+1 FROM `table_name`), 1), false) ``
+
+### 未来的任务
+
+目前，我们正在进行一些重构，以完成以下任务：
+
+- 纠正不符合规则的代码。
+- `models`中的文件太多了，所以我们正在将其中的一些移动到子包`models/xxx`中。
+- 由于它们依赖于`models`，因此应将某些`modules`子包移动到`services`中。
diff --git a/docs/document/contributing/guidelines-frontend.md b/docs/document/contributing/guidelines-frontend.md
new file mode 100644
index 0000000..4f34789
--- /dev/null
+++ b/docs/document/contributing/guidelines-frontend.md
@@ -0,0 +1,149 @@
+---
+date: "2023-05-25T16:00:00+02:00"
+slug: "guidelines-frontend"
+sidebar_position: 20
+aliases:
+  - /zh-cn/guidelines-frontend
+---
+
+# 前端开发指南
+
+## 背景
+
+Gitea 在其前端中使用[Fomantic-UI](https://fomantic-ui.com/introduction/getting-started.html)（基于[jQuery](https://api.jquery.com)）和 [Vue3](https://vuejs.org/)。
+
+HTML 页面由[Go HTML Template](https://pkg.go.dev/html/template)渲染。
+
+源文件可以在以下目录中找到：
+
+- **CSS 样式**： `web_src/css/`
+- **JavaScript 文件**： `web_src/js/`
+- **Vue 组件**： `web_src/js/components/`
+- **Go HTML 模板**： `templates/`
+
+## 通用准则
+
+我们推荐使用[Google HTML/CSS Style Guide](https://google.github.io/styleguide/htmlcssguide.html)和[Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html)。
+
+## Gitea 特定准则
+
+1. 每个功能（Fomantic-UI/jQuery 模块）应放在单独的文件/目录中。
+2. HTML 的 id 和 class 应使用 kebab-case，最好包含 2-3 个与功能相关的关键词。
+3. 在 JavaScript 中使用的 HTML 的 id 和 class 应在整个项目中是唯一的，并且应包含 2-3 个与功能相关的关键词。建议在仅在 JavaScript 中使用的 class 中使用 `js-` 前缀。
+4. 不应覆盖框架提供的 class 的 CSS 样式。始终使用具有 2-3 个与功能相关的关键词的新 class 名称来覆盖框架样式。Gitea 中的帮助 CSS 类在 `helpers.less` 中。
+5. 后端可以通过使用`ctx.PageData["myModuleData"] = map[]{}`将复杂数据传递给前端，但不要将整个模型暴露给前端，以避免泄露敏感数据。
+6. 简单页面和与 SEO 相关的页面使用 Go HTML 模板渲染生成静态的 Fomantic-UI HTML 输出。复杂页面可以使用 Vue3。
+7. 明确变量类型，优先使用`elem.disabled = true`而不是`elem.setAttribute('disabled', 'anything')`，优先使用`$el.prop('checked', var === 'yes')`而不是`$el.prop('checked', var)`。
+8. 使用语义化元素，优先使用`<button class="ui button">`而不是`<div class="ui button">`。
+9. 避免在 CSS 中使用不必要的`!important`，如果无法避免，添加注释解释为什么需要它。
+10. 避免在一个事件监听器中混合不同的事件，优先为每个事件使用独立的事件监听器。
+11. 推荐使用自定义事件名称前缀`ce-`。
+12. 建议使用 Tailwind CSS，它可以通过 `tw-` 前缀获得，例如 `tw-relative`. Gitea 自身的助手类 CSS 使用 `gt-` 前缀（`gt-ellipsis`），Gitea 自身的私有框架级 CSS 类使用 `g-` 前缀（`g-modal-confirm`）。
+13. 尽量避免内联脚本和样式，建议将 JS 代码放入 JS 文件中并使用 CSS 类。如果内联脚本和样式不可避免，请解释无法避免的原因。
+
+### 可访问性 / ARIA
+
+在历史上，Gitea 大量使用了可访问性不友好的框架 Fomantic UI。
+Gitea 使用一些补丁使 Fomantic UI 更具可访问性（参见 `aria.md`），
+但仍然存在许多问题需要大量的工作和时间来修复。
+
+### 框架使用
+
+不建议混合使用不同的框架，这会使代码难以维护。
+一个 JavaScript 模块应遵循一个主要框架，并遵循该框架的最佳实践。
+
+推荐的实现方式：
+
+- Vue + Vanilla JS
+- Fomantic-UI（jQuery）
+- htmx （部分页面重新加载其他静态组件）
+- Vanilla JS
+
+不推荐的实现方式：
+
+- Vue + Fomantic-UI（jQuery）
+- jQuery + Vanilla JS
+- htmx + 任何其他需要大量 JavaScript 代码或不必要的功能，如 htmx 脚本 (`hx-on`)
+
+为了保持界面一致，Vue 组件可以使用 Fomantic-UI 的 CSS 类。
+尽管不建议混合使用不同的框架，
+我们使用 htmx 进行简单的交互。您可以在此 [PR](https://github.com/go-gitea/gitea/pull/28908) 中查看一个简单交互的示例，其中应使用 htmx。如果您需要更高级的反应性，请不要使用 htmx，请使用其他框架（Vue/Vanilla JS）。
+但如果混合使用是必要的，并且代码设计良好且易于维护，也可以工作。
+
+### `async` 函数
+
+只有当函数内部存在`await`调用或返回`Promise`时，才将函数标记为`async`。
+
+不建议使用`async`事件监听器，这可能会导致问题。
+原因是`await`后的代码在事件分发之外执行。
+参考：https://github.com/github/eslint-plugin-github/blob/main/docs/rules/async-preventdefault.md
+
+如果一个事件监听器必须是`async`，应在任何`await`之前使用`e.preventDefault()`，
+建议将其放在函数的开头。
+
+如果我们想在非异步上下文中调用`async`函数，
+建议使用`const _promise = asyncFoo()`来告诉读者
+这是有意为之的，我们想调用异步函数并忽略 Promise。
+一些 lint 规则和 IDE 也会在未处理返回的 Promise 时发出警告。
+
+### 获取数据
+
+要获取数据，请使用`modules/fetch.js`中的包装函数`GET`、`POST`等。他们
+接受内容的`data`选项，将自动设置 CSRF 令牌并返回
+[Response](https://developer.mozilla.org/en-US/docs/Web/API/Response)。
+
+### HTML 属性和 dataset
+
+禁止使用`dataset`，它的驼峰命名行为使得搜索属性变得困难。
+然而，仍然存在一些特殊情况，因此当前的准则是：
+
+- 对于旧代码：
+
+  - 应将`$.data()`重构为`$.attr()`。
+  - 在极少数情况下，可以使用`$.data()`将一些非字符串数据绑定到元素上，但强烈不推荐使用。
+
+- 对于新代码：
+  - 不应使用`node.dataset`，而应使用`node.getAttribute`。
+  - 不要将任何用户数据绑定到 DOM 节点上，使用合适的设计模式描述节点和数据之间的关系。
+
+### 显示/隐藏元素
+
+- 推荐在 Vue 组件中使用`v-if`和`v-show`来显示/隐藏元素。
+- Go 模板代码应使用 `.tw-hidden` 和 `showElem()/hideElem()/toggleElem()` 来显示/隐藏元素，请参阅`.tw-hidden`的注释以获取更多详细信息。
+
+### Go HTML 模板中的样式和属性
+
+建议使用以下方式：
+
+```html
+<div
+  class="gt-name1 gt-name2 {{if .IsFoo}}gt-foo{{end}}"
+  {{if
+  .IsFoo}}data-foo{{end}}
+></div>
+```
+
+而不是：
+
+```html
+<div
+  class="gt-name1 gt-name2{{if .IsFoo}} gt-foo{{end}}"
+  {{if
+  .IsFoo}}
+  data-foo{{end}}
+></div>
+```
+
+以使代码更易读。
+
+### 旧代码
+
+许多旧代码已经存在于本文撰写之前。建议重构旧代码以遵循指南。
+
+### Vue3 和 JSX
+
+Gitea 现在正在使用 Vue3。我们决定不引入 JSX，以保持 HTML 代码和 JavaScript 代码分离。
+
+### UI 示例
+
+Gitea 使用一些自制的 UI 元素并自定义其他元素，以将它们更好地集成到通用 UI 方法中。当在开发模式（`RUN_MODE=dev`）下运行 Gitea 时，在 `http(s)://your-gitea-url:port/devtest` 下会提供一个包含一些标准化 UI 示例的页面。
diff --git a/docs/document/contributing/guidelines-refactoring.md b/docs/document/contributing/guidelines-refactoring.md
new file mode 100644
index 0000000..6df2944
--- /dev/null
+++ b/docs/document/contributing/guidelines-refactoring.md
@@ -0,0 +1,40 @@
+---
+date: "2023-05-25T00:00:00+00:00"
+slug: "guidelines-refactoring"
+sidebar_position: 20
+aliases:
+  - /zh-cn/guidelines-refactoring
+---
+
+# 重构指南
+
+## 背景
+
+自 2014 年 2 月 12 日编写了第一行代码以来，Gitea 已经发展成为一个庞大的项目。
+因此，代码库变得越来越大。代码库越大，维护就越困难。
+存在许多过时的机制，许多框架混合在一起，一些遗留代码可能会导致错误并阻碍新功能的开发。
+为了使代码库更易于维护，使 Gitea 变得更好，开发人员应牢记使用现代机制来重构旧代码。
+
+本文档是关于重构代码库的指南集合。
+
+## 重构建议
+
+- 设计更多关于未来的内容，而不仅仅解决当前问题。
+- 减少模糊性，减少冲突，提高可维护性。
+- 描述重构，例如：
+  - 为什么需要重构。
+  - 如何解决旧问题。
+  - 重构的优点/缺点是什么。
+- 只做必要的更改，尽量保留旧逻辑。
+- 引入一些中间步骤，使重构更容易审查，完整的重构计划可以在几个 PR 中完成。
+- 如果存在分歧，应该请 TOC（技术监督委员会）参与决策。
+- 添加必要的测试以确保重构的正确性。
+- 非错误重构优先在里程碑的开始时进行，这样可以更容易地在发布之前发现问题。
+
+## 审查和合并建议
+
+- 重构的 PR 不应该长时间保持打开状态（通常为 7 天），应尽快进行审查。
+- 重构的 PR 应尽快合并，不应被其他 PR 阻塞。
+- 如果 TOC 没有异议，重构的 PR 可以在 7 天后由一名核心成员（非作者）批准后合并。
+- 如果最终结果良好，容忍一些不完美/临时的步骤。
+- 如果重构是必要的，容忍一些回归错误，并尽快修复错误。
diff --git a/docs/document/contributing/localization.md b/docs/document/contributing/localization.md
new file mode 100644
index 0000000..e0b81a3
--- /dev/null
+++ b/docs/document/contributing/localization.md
@@ -0,0 +1,25 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+slug: "localization"
+sidebar_position: 70
+aliases:
+  - /zh-cn/localization
+---
+
+# 本地化
+
+Gitea 的本地化是通过我们的[Crowdin 项目](https://crowdin.com/project/gitea)进行的。
+
+对于对**英语翻译**的更改，可以发出 pull-request，来更改[英语语言环境](https://github.com/go-gitea/gitea/blob/main/options/locale/locale_en-US.ini)中合适的关键字。
+
+有关对**非英语**翻译的更改，请参阅上面的 Crowdin 项目。
+
+## 支持的语言
+
+上述 Crowdin 项目中列出的任何语言一旦翻译了 25% 或更多都将得到支持。
+
+翻译被接受后，它将在下一次 Crowdin 同步后反映在主存储库中，这通常是在任何 PR 合并之后。
+
+在撰写本文时，这意味着更改后的翻译可能要到 Gitea 的下一个版本才会出现。
+
+如果使用开发版本，则在同步更改内容后，它应该会在更新后立即显示。
diff --git a/docs/document/development/api-usage.md b/docs/document/development/api-usage.md
new file mode 100644
index 0000000..c649654
--- /dev/null
+++ b/docs/document/development/api-usage.md
@@ -0,0 +1,63 @@
+---
+date: "2018-06-24:00:00+02:00"
+slug: "api-usage"
+sidebar_position: 40
+aliases:
+  - /zh-cn/api-usage
+---
+
+# API 使用指南
+
+## 开启/配置 API 访问
+
+通常情况下， `ENABLE_SWAGGER` 默认开启并且参数 `MAX_RESPONSE_ITEMS` 默认为 50。您可以从 [Config Cheat Sheet](../administration/config-cheat-sheet.md) 中获取更多配置相关信息。
+
+## 通过 API 认证
+
+Gitea 支持以下几种 API 认证方式：
+
+- HTTP basic authentication 方式
+- 通过指定 `token=...` URL 查询参数方式
+- 通过指定 `access_token=...` URL 查询参数方式
+- 通过指定 `Authorization: token ...` HTTP header 方式
+
+以上提及的认证方法接受相同的 apiKey token 类型，您可以在编码时通过查阅代码更好地理解这一点。
+Gitea 调用解析查询参数以及头部信息来获取 token 的代码可以在 [modules/auth/auth.go](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47) 中找到。
+
+您可以通过您的 gitea web 界面来创建 apiKey token：
+`Settings | Applications | Generate New Token`.
+
+### 关于 `Authorization:` header
+
+由于一些历史原因，Gitea 需要在 header 的 apiKey token 里引入前缀 `token`，类似于如下形式：
+
+```
+Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675
+```
+
+以 `curl` 命令为例，它会以如下形式携带在请求中：
+
+```
+curl "http://localhost:4000/api/v1/repos/test1/test1/issues" \
+    -H "accept: application/json" \
+    -H "Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675" \
+    -H "Content-Type: application/json" -d "{ \"body\": \"testing\", \"title\": \"test 20\"}" -i
+```
+
+正如上例所示，您也可以在 GET 请求中使用同一个 token 并以 `token=` 的查询参数形式携带 token 来进行认证。
+
+## 通过 API 列出您发布的令牌
+
+`/users/:name/tokens` 是一个特殊的接口，需要您使用 basic authentication 进行认证，具体原因在 issue 中
+[#3842](https://github.com/go-gitea/gitea/issues/3842#issuecomment-397743346) 有所提及，使用方法如下所示：
+
+### 使用 Basic authentication 认证
+
+```
+$ curl --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens
+[{"name":"test","sha1":"..."},{"name":"dev","sha1":"..."}]
+```
+
+## 使用 Sudo 方式请求 API
+
+此 API 允许管理员借用其他用户身份进行 API 请求。只需在请求中指定查询参数 `sudo=` 或是指定 header 中的 `Sudo:` 为需要使用的用户 username 即可。
diff --git a/docs/document/development/hacking-on-gitea.md b/docs/document/development/hacking-on-gitea.md
new file mode 100644
index 0000000..0a802f2
--- /dev/null
+++ b/docs/document/development/hacking-on-gitea.md
@@ -0,0 +1,334 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+slug: "hacking-on-gitea"
+sidebar_position: 10
+aliases:
+  - /zh-cn/hacking-on-gitea
+---
+
+# 玩转 Gitea
+
+## 快速入门
+
+要获得快速工作的开发环境，您可以使用 Gitpod。
+
+[![在 Gitpod 中打开](../../static/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/go-gitea/gitea)
+
+## 安装 Golang
+
+您需要 [安装 go](https://go.dev/doc/install) 并设置您的 go 环境。
+
+接下来，[使用 npm 安装 Node.js](https://nodejs.org/en/download/) ，这是构建
+JavaScript 和 CSS 文件的必要工具。最低支持的 Node.js 版本是 @minNodeVersion@
+并且推荐使用最新的 LTS 版本。
+
+**注意** ：当执行需要外部工具的 make 任务时，比如
+`make watch-backend`，Gitea 会自动下载并构建这些必要的组件。为了能够使用这些，你必须
+将 `"$GOPATH"/bin` 目录加入到可执行路径上。如果你不把 go bin 目录添加到可执行路径你必须手动
+指定可执行程序路径。
+
+**注意 2** ：Go 版本 @minGoVersion@ 或更高版本是必须的。Gitea 使用 `gofmt` 来
+格式化源代码。然而，`gofmt` 的结果可能因 `go` 的版本而有差异。因此推荐安装我们持续集成使用
+的 Go 版本。截至上次更新，Go 版本应该是 @goVersion@。
+
+## 安装 Make
+
+Gitea 大量使用 `Make` 来自动化任务和改进开发。本指南涵盖了如何安装 Make。
+
+### 在 Linux 上
+
+使用包管理器安装。
+
+在 Ubuntu/Debian 上：
+
+```bash
+sudo apt-get install make
+```
+
+在 Fedora/RHEL/CentOS 上：
+
+```bash
+sudo yum install make
+```
+
+### 在 Windows 上
+
+Make 的这三个发行版都可以在 Windows 上运行：
+
+- [单个二进制构建](http://www.equation.com/servlet/equation.cmd?fa=make)。复制到某处并添加到 `PATH`。
+  - [32 位版本](http://www.equation.com/ftpdir/make/32/make.exe)
+  - [64 位版本](http://www.equation.com/ftpdir/make/64/make.exe)
+- [MinGW-w64](https://www.mingw-w64.org) / [MSYS2](https://www.msys2.org/)。
+  - MSYS2 是一个工具和库的集合，为您提供一个易于使用的环境来构建、安装和运行本机 Windows 软件，它包括 MinGW-w64。
+  - 在 MingGW-w64 中，二进制文件称为 `mingw32-make.exe` 而不是 `make.exe`。将 `bin` 文件夹添加到 `PATH`。
+  - 在 MSYS2 中，您可以直接使用 `make`。请参阅 [MSYS2 移植](https://www.msys2.org/wiki/Porting/)。
+  - 要使用 CGO_ENABLED（例如：SQLite3）编译 Gitea，您可能需要使用 [tdm-gcc](https://jmeubank.github.io/tdm-gcc/) 而不是 MSYS2 gcc，因为 MSYS2 gcc 标头缺少一些 Windows -只有 CRT 函数像 \_beginthread 一样。
+- [Chocolatey 包管理器](https://chocolatey.org/packages/make)。运行`choco install make`
+
+**注意** ：如果您尝试在 Windows 命令提示符下使用 make 进行构建，您可能会遇到问题。建议使用上述提示（Git bash 或 MinGW），但是如果您只有命令提示符（或可能是 PowerShell），则可以使用 [set](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1) 命令，例如 `set TAGS=bindata`。
+
+## 下载并克隆 Gitea 源代码
+
+获取源代码的推荐方法是使用 `git clone`。
+
+```bash
+git clone https://github.com/go-gitea/gitea
+```
+
+（自从 go modules 出现后，不再需要构建 go 项目从 `$GOPATH` 中获取，因此不再推荐使用 `go get` 方法。）
+
+## 派生 Gitea
+
+如上所述下载主要的 Gitea 源代码。然后，派生 [Gitea 仓库](https://github.com/go-gitea/gitea)，
+并为您的本地仓库切换 git 远程源，或添加另一个远程源：
+
+```bash
+# 将原来的 Gitea origin 重命名为 upstream
+git remote rename origin upstream
+git remote add origin "git@github.com:$GITHUB_USERNAME/gitea.git"
+git fetch --all --prune
+```
+
+或者：
+
+```bash
+# 为我们的 fork 添加新的远程
+git remote add "$FORK_NAME" "git@github.com:$GITHUB_USERNAME/gitea.git"
+git fetch --all --prune
+```
+
+为了能够创建合并请求，应将分叉存储库添加为 Gitea 本地仓库的远程，否则无法推送更改。
+
+## 构建 Gitea（基本）
+
+看看我们的
+[说明](installation/from-source.md)
+关于如何[从源代码构建](installation/from-source.md) 。
+
+从源代码构建的最简单推荐方法是：
+
+```bash
+TAGS="bindata sqlite sqlite_unlock_notify" make build
+```
+
+`build` 目标将同时执行 `frontend` 和 `backend` 子目标。如果存在 `bindata` 标签，资源文件将被编译成二进制文件。建议在进行前端开发时省略 `bindata` 标签，以便实时反映更改。
+
+有关所有可用的 `make` 目标，请参阅 `make help`。另请参阅 [`.drone.yml`](https://github.com/go-gitea/gitea/blob/main/.drone.yml) 以了解我们的持续集成是如何工作的。
+
+## 持续构建
+
+要在源文件更改时运行并持续构建：
+
+```bash
+# 对于前端和后端
+make watch
+
+# 或者：只看前端文件（html/js/css）
+make watch-frontend
+
+# 或者：只看后端文件 (go)
+make watch-backend
+```
+
+在 macOS 上，监视所有后端源文件可能会达到默认的打开文件限制，这可以通过当前 shell 的 `ulimit -n 12288` 或所有未来 shell 的 shell 启动文件来增加。
+
+### 格式化、代码分析和拼写检查
+
+我们的持续集成将拒绝未通过代码检查（包括格式检查、代码分析和拼写检查）的 PR。
+
+你应该格式化你的代码：
+
+```bash
+make fmt
+```
+
+并检查源代码：
+
+```bash
+# lint 前端和后端代码
+make lint
+# 仅 lint 后端代码
+make lint-backend
+```
+
+**注意** ：`gofmt` 的结果取决于 `go` 的版本。您应该运行与持续集成相同的 go 版本。
+
+### 处理 JS 和 CSS
+
+前端开发应遵循 [Guidelines for Frontend Development](contributing/guidelines-frontend.md)。
+
+要使用前端资源构建，请使用上面提到的“watch-frontend”目标或只构建一次：
+
+```bash
+make build && ./gitea
+```
+
+在提交之前，确保 linters 通过：
+
+```bash
+make lint-frontend
+```
+
+### 配置本地 ElasticSearch 实例
+
+使用 docker 启动本地 ElasticSearch 实例：
+
+```sh
+mkdir -p $(pwd) /data/elasticsearch
+sudo chown -R 1000:1000 $(pwd) /data/elasticsearch
+docker run --rm --memory= "4g" -p 127.0.0.1:9200:9200 -p 127.0.0.1:9300:9300 -e "discovery.type=single-node" -v "$(pwd)/data /elasticsearch:/usr/share/elasticsearch/data" docker.elastic.co/elasticsearch/elasticsearch:7.16.3
+```
+
+配置`app.ini`：
+
+```ini
+[indexer]
+ISSUE_INDEXER_TYPE = elasticsearch
+ISSUE_INDEXER_CONN_STR = http://elastic:changeme@localhost:9200
+REPO_INDEXER_ENABLED = true
+REPO_INDEXER_TYPE = elasticsearch
+REPO_INDEXER_CONN_STR = http://elastic:changeme@localhost:9200
+```
+
+### 构建和添加 SVGs
+
+SVG 图标是使用 `make svg` 命令构建的，该命令将图标资源编译到输出目录 `public/assets/img/svg` 中。可以在 `web_src/svg` 目录中添加自定义图标。
+
+### 构建 Logo
+
+Gitea Logo 的 PNG 和 SVG 版本是使用 `TAGS="gitea" make generate-images` 目标从单个 SVG 源文件 assets/logo.svg 构建的。要运行它，Node.js 和 npm 必须可用。
+
+通过更新 `assets/logo.svg` 并运行 `make generate-images`，同样的过程也可用于从 SVG 源文件生成自定义 Logo PNG。忽略 gitea 编译选项将仅更新用户指定的 LOGO 文件。
+
+### 更新 API
+
+创建新的 API 路由或修改现有的 API 路由时，您**必须**
+更新和/或创建 [Swagger](https://swagger.io/docs/specification/2-0/what-is-swagger/)
+这些使用 [go-swagger](https://goswagger.io/) 评论的文档。
+[规范](https://goswagger.io/use/spec.html#annotation-syntax)中描述了这些注释的结构。
+如果您想了解更多有关 Swagger 结构的信息，可以查看
+[Swagger 2.0 文档](https://swagger.io/docs/specification/2-0/basic-structure/)
+或与添加新 API 端点的先前 PR 进行比较，例如 [PR #5483](https://github.com/go-gitea/gitea/pull/5843/files#diff-2e0a7b644cf31e1c8ef7d76b444fe3aaR20)
+
+您应该注意不要破坏下游用户依赖的 API。在稳定的 API 上，一般来说添加是可以接受的，但删除
+或对 API 进行根本性更改将会被拒绝。
+
+创建或更改 API 端点后，请用以下命令重新生成 Swagger 文档：
+
+```bash
+make generate-swagger
+```
+
+您应该验证生成的 Swagger 文件：
+
+```bash
+make swagger-validate
+```
+
+您应该提交更改后的 swagger JSON 文件。持续集成服务器将使用以下方法检查是否已完成：
+
+```bash
+make swagger-check
+```
+
+**注意** ：请注意，您应该使用 Swagger 2.0 文档，而不是 OpenAPI 3 文档。
+
+### 创建新的配置选项
+
+创建新的配置选项时，将它们添加到 `modules/setting` 的对应文件。您应该将信息添加到 `custom/conf/app.ini`
+并到[配置备忘单](../administration/config-cheat-sheet.md)
+在 `docs/content/doc/advanced/config-cheat-sheet.zh-cn.md` 中找到
+
+### 更改 Logo
+
+更改 Gitea Logo SVG 时，您将需要运行并提交结果的：
+
+```bash
+make generate-images
+```
+
+这将创建必要的 Gitea 图标和其他图标。
+
+### 数据库迁移
+
+如果您对数据库中的任何数据库持久结构进行重大更改
+`models/` 目录，您将需要进行新的迁移。可以找到这些
+在 `models/migrations/` 中。您可以确保您的迁移适用于主要
+数据库类型使用：
+
+```bash
+make test-sqlite-migration # 将 SQLite 切换为适当的数据库
+```
+
+## 测试
+
+Gitea 运行两种类型的测试：单元测试和集成测试。
+
+### 单元测试
+
+`go test` 系统中的`*_test.go` 涵盖了单元测试。
+您可以设置环境变量 `GITEA_UNIT_TESTS_LOG_SQL=1` 以在详细模式下运行测试时显示所有 SQL 语句（即设置`GOTESTFLAGS=-v` 时）。
+
+```bash
+TAGS="bindata sqlite sqlite_unlock_notify" make test # Runs the unit tests
+```
+
+### 集成测试
+
+单元测试不会也不能完全单独测试 Gitea。因此，我们编写了集成测试；但是，这些依赖于数据库。
+
+```bash
+TAGS="bindata sqlite sqlite_unlock_notify" make build test-sqlite
+```
+
+将在 SQLite 环境中运行集成测试。集成测试需要安装 `git lfs`。其他数据库测试可用，但
+可能需要适应当地环境。
+
+看看 [`tests/integration/README.md`](https://github.com/go-gitea/gitea/blob/main/tests/integration/README.md) 有关更多信息以及如何运行单个测试。
+
+### 测试 PR
+
+我们的持续集成将测试代码是否通过了单元测试，并且所有支持的数据库都将在 Docker 环境中通过集成测试。
+还将测试从几个最新版本的 Gitea 迁移。
+
+请在 PR 中附带提交适当的单元测试和集成测试。
+
+## 网站文档
+
+该网站的文档位于 `docs/` 中。如果你改变了文档内容，你可以使用以下测试方法进行持续集成：
+
+```bash
+make lint-md
+```
+
+## Visual Studio Code
+
+`contrib/ide/vscode` 中为 Visual Studio Code 提供了 `launch.json` 和 `tasks.json`。查看
+[`contrib/ide/README.md`](https://github.com/go-gitea/gitea/blob/main/contrib/ide/README.md) 了解更多信息。
+
+## Goland
+
+单击 `/main.go` 中函数 `func main()` 上的 `Run Application` 箭头
+可以快速启动一个可调试的 Gitea 实例。
+
+`Run/Debug Configuration` 中的 `Output Directory` 必须设置为
+gitea 项目目录（包含 `main.go` 和 `go.mod`），
+否则，启动实例的工作目录是 GoLand 的临时目录
+并防止 Gitea 在开发环境中加载动态资源（例如：模板）。
+
+要在 GoLand 中使用 SQLite 运行单元测试，请设置 `-tags sqlite,sqlite_unlock_notify`
+在 `运行/调试配置` 的 `Go 工具参数` 中。
+
+## 提交 PR
+
+对更改感到满意后，将它们推送并打开拉取请求。它建议您允许 Gitea Managers 和 Owners 修改您的 PR
+分支，因为我们需要在合并之前将其更新为 main 和/或可能是能够直接帮助解决问题。
+
+任何 PR 都需要 Gitea 维护者的两次批准，并且需要通过持续集成。看看我们的
+[CONTRIBUTING.md](https://github.com/go-gitea/gitea/blob/main/CONTRIBUTING.md)
+文档。
+
+如果您需要更多帮助，请访问 [Discord](https://discord.gg/gitea) #Develop 频道
+并在那里聊天。
+
+现在，您已准备好 Hacking Gitea。
diff --git a/docs/document/development/integrations.md b/docs/document/development/integrations.md
new file mode 100644
index 0000000..049d0bb
--- /dev/null
+++ b/docs/document/development/integrations.md
@@ -0,0 +1,37 @@
+---
+date: "2023-05-25T17:29:00+08:00"
+slug: "integrations"
+sidebar_position: 65
+aliases:
+  - /zh-cn/integrations
+---
+
+# 集成
+
+Gitea 拥有一个出色的第三方集成社区，以及在其他各种项目中的一流支持。
+
+我们正在[awesome-gitea](https://gitea.com/gitea/awesome-gitea)上整理一个列表来跟踪这些集成！
+
+如果你正在寻找[CI/CD](https://gitea.com/gitea/awesome-gitea#user-content-devops)，
+一个[SDK](https://gitea.com/gitea/awesome-gitea#user-content-sdk)，
+甚至一些额外的[主题](https://gitea.com/gitea/awesome-gitea#user-content-themes)，
+你可以在[awesome-gitea](https://gitea.com/gitea/awesome-gitea)中找到它们的列表！
+
+## 预填新文件名和内容
+
+如果你想打开一个具有给定名称和内容的新文件，
+你可以使用查询参数来实现：
+
+```txt
+GET /{{org}}/{{repo}}/_new/{{filepath}}
+    ?filename={{filename}}
+    &value={{content}}
+```
+
+例如：
+
+```txt
+GET https://git.example.com/johndoe/bliss/_new/articles/
+    ?filename=hello-world.md
+    &value=Hello%2C%20World!
+```
diff --git a/docs/document/development/migrations.md b/docs/document/development/migrations.md
new file mode 100644
index 0000000..60cad1a
--- /dev/null
+++ b/docs/document/development/migrations.md
@@ -0,0 +1,31 @@
+---
+date: "2023-05-25T17:29:00+08:00"
+slug: "migrations-interfaces"
+sidebar_position: 55
+aliases:
+  - /zh-cn/migrations-interfaces
+---
+
+# 迁移接口
+
+完整迁移功能在 Gitea 1.9.0 版本中引入。它定义了两个接口，用于支持从其他 Git 托管平台迁移存储库数据到 Gitea，或者在将来将 Gitea 数据迁移到其他 Git 托管平台。
+
+目前已实现了从 GitHub、GitLab 和其他 Gitea 实例的迁移。
+
+首先，Gitea 在包[modules/migration](https://github.com/go-gitea/gitea/tree/main/modules/migration)中定义了一些标准对象。它们是`Repository`、`Milestone`、`Release`、`ReleaseAsset`、`Label`、`Issue`、`Comment`、`PullRequest`、`Reaction`、`Review`、`ReviewComment`。
+
+## 下载器接口
+
+要从新的 Git 托管平台迁移，需要进行两个步骤的更新。
+
+- 您应该实现一个`Downloader`，用于获取存储库信息。
+- 您应该实现一个`DownloaderFactory`，用于检测 URL 是否匹配，并创建上述的`Downloader`。
+  - 您需要在`init()`中通过`RegisterDownloaderFactory`注册`DownloaderFactory`。
+
+您可以在[downloader.go](https://github.com/go-gitea/gitea/blob/main/modules/migration/downloader.go)中找到这些接口。
+
+## 上传器接口
+
+目前，只实现了`GiteaLocalUploader`，因此我们只能通过此 Uploader 将下载的数据保存到本地的 Gitea 实例。目前不支持其他上传器。
+
+您可以在[uploader.go](https://github.com/go-gitea/gitea/blob/main/modules/migration/uploader.go)中找到这些接口。
diff --git a/docs/document/development/oauth2-provider.md b/docs/document/development/oauth2-provider.md
new file mode 100644
index 0000000..1baa28c
--- /dev/null
+++ b/docs/document/development/oauth2-provider.md
@@ -0,0 +1,128 @@
+---
+date: "2019-04-19:44:00+01:00"
+slug: "oauth2-provider"
+sidebar_position: 41
+aliases:
+  - /zh-cn/oauth2-provider
+---
+
+# OAuth2 提供者
+
+Gitea 支持作为 OAuth2 提供者，允许第三方应用程序在用户同意的情况下访问其资源。此功能自 1.8.0 版起可用。
+
+## 端点
+
+| 端点                     | URL                                 |
+| ------------------------ | ----------------------------------- |
+| OpenID Connect Discovery | `/.well-known/openid-configuration` |
+| Authorization Endpoint   | `/login/oauth/authorize`            |
+| Access Token Endpoint    | `/login/oauth/access_token`         |
+| OpenID Connect UserInfo  | `/login/oauth/userinfo`             |
+| JSON Web Key Set         | `/login/oauth/keys`                 |
+
+## 支持的 OAuth2 授权
+
+目前 Gitea 仅支持 [**Authorization Code Grant**](https://tools.ietf.org/html/rfc6749#section-1.3.1) 标准，并额外支持以下扩展：
+
+- [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636)
+- [OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth)
+
+要将 Authorization Code Grant 作为第三方应用程序，您需要通过在设置中添加一个新的 "应用程序" (`/user/settings/applications`)。
+
+## 范围
+
+Gitea 支持以下令牌范围:
+
+| 名称                                     | 介绍                                                            |
+| ---------------------------------------- | --------------------------------------------------------------- |
+| **(no scope)**                           | 授予对公共用户配置文件和公共存储库的只读访问权限                |
+| **repo**                                 | 完全控制所有存储库                                              |
+| &nbsp;&nbsp;&nbsp; **repo:status**       | 授予对所有存储库中提交状态的读/写访问权限                       |
+| &nbsp;&nbsp;&nbsp; **public_repo**       | 仅授予对公共存储库的读/写访问权限                               |
+| **admin:repo_hook**                      | 授予对所有存储库的 Hooks 访问权限，该权限已包含在 `repo` 范围中 |
+| &nbsp;&nbsp;&nbsp; **write:repo_hook**   | 授予对存储库 Hooks 的读/写访问权限                              |
+| &nbsp;&nbsp;&nbsp; **read:repo_hook**    | 授予对存储库 Hooks 的只读访问权限                               |
+| **admin:org**                            | 授予对组织设置的完全访问权限                                    |
+| &nbsp;&nbsp;&nbsp; **write:org**         | 授予对组织设置的读/写访问权限                                   |
+| &nbsp;&nbsp;&nbsp; **read:org**          | 授予对组织设置的只读访问权限                                    |
+| **admin:public_key**                     | 授予公钥管理的完全访问权限                                      |
+| &nbsp;&nbsp;&nbsp; **write:public_key**  | 授予对公钥的读/写访问权限                                       |
+| &nbsp;&nbsp;&nbsp; **read:public_key**   | 授予对公钥的只读访问权限                                        |
+| **admin:org_hook**                       | 授予对组织级别 Hooks 的完全访问权限                             |
+| **admin:user_hook**                      | 授予对用户级别 Hooks 的完全访问权限                             |
+| **notification**                         | 授予对通知的完全访问权限                                        |
+| **user**                                 | 授予对用户个人资料信息的完全访问权限                            |
+| &nbsp;&nbsp;&nbsp; **read:user**         | 授予对用户个人资料的读取权限                                    |
+| &nbsp;&nbsp;&nbsp; **user:email**        | 授予对用户电子邮件地址的读取权限                                |
+| &nbsp;&nbsp;&nbsp; **user:follow**       | 授予访问权限以关注/取消关注用户                                 |
+| **delete_repo**                          | 授予删除存储库的权限                                            |
+| **package**                              | 授予对托管包的完全访问权限                                      |
+| &nbsp;&nbsp;&nbsp; **write:package**     | 授予对包的读/写访问权限                                         |
+| &nbsp;&nbsp;&nbsp; **read:package**      | 授予对包的读取权限                                              |
+| &nbsp;&nbsp;&nbsp; **delete:package**    | 授予对包的删除权限                                              |
+| **admin:gpg_key**                        | 授予 GPG 密钥管理的完全访问权限                                 |
+| &nbsp;&nbsp;&nbsp; **write:gpg_key**     | 授予对 GPG 密钥的读/写访问权限                                  |
+| &nbsp;&nbsp;&nbsp; **read:gpg_key**      | 授予对 GPG 密钥的只读访问权限                                   |
+| **admin:application**                    | 授予应用程序管理的完全访问权限                                  |
+| &nbsp;&nbsp;&nbsp; **write:application** | 授予应用程序管理的读/写访问权限                                 |
+| &nbsp;&nbsp;&nbsp; **read:application**  | 授予应用程序管理的读取权限                                      |
+| **sudo**                                 | 允许以站点管理员身份执行操作                                    |
+
+## 客户端类型
+
+Gitea 支持私密和公共客户端类型，[参见 RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1).
+
+对于公共客户端, 允许在本地回环地址的重定向 URI 中使用任意端口，例如 `http://127.0.0.1/`。根据 [RFC 8252 的建议](https://datatracker.ietf.org/doc/html/rfc8252#section-8.3)，请避免使用 `localhost`。
+
+## 示例
+
+**注意：** 该示例中尚未使用 PKCE。
+
+1. 将用户重定向到授权端点，以获得他们的访问资源授权:
+
+   ```curl
+   https://[YOUR-GITEA-URL]/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI& response_type=code&state=STATE
+   ```
+
+   在设置中注册应用程序以获得 `CLIENT_ID`。`STATE` 是一个随机字符串，它将在获得用户授权后发送回您的应用程序。`state` 参数是可选的，但您应该使用它来防止 CSRF 攻击。
+
+   ![Authorization Page](../../static/authorize.png)
+
+   用户将会被询问是否授权给您的应用程序。如果他们同意了授权，用户将会被重定向到 `REDIRECT_URL`，例如：
+
+   ```curl
+   https://[REDIRECT_URI]?code=RETURNED_CODE&state=STATE
+   ```
+
+2. 使用重定向提供的 `code`，您可以请求一个新的应用程序和 Refresh Token。Access Token Endpoint 接受 `application/json` 或 `application/x-www-form-urlencoded` 类型的 POST 请求，例如：
+
+   ```curl
+   POST https://[YOUR-GITEA-URL]/login/oauth/access_token
+   ```
+
+   ```json
+   {
+     "client_id": "YOUR_CLIENT_ID",
+     "client_secret": "YOUR_CLIENT_SECRET",
+     "code": "RETURNED_CODE",
+     "grant_type": "authorization_code",
+     "redirect_uri": "REDIRECT_URI"
+   }
+   ```
+
+   返回：
+
+   ```json
+   {
+     "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjowLCJleHAiOjE1NTUxNzk5MTIsImlhdCI6MTU1NTE3NjMxMn0.0-iFsAwBtxuckA0sNZ6QpBQmywVPz129u75vOM7wPJecw5wqGyBkmstfJHAjEOqrAf_V5Z-1QYeCh_Cz4RiKug",
+     "token_type": "bearer",
+     "expires_in": 3600,
+     "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjoxLCJjbnQiOjEsImV4cCI6MTU1NzgwNDMxMiwiaWF0IjoxNTU1MTc2MzEyfQ.S_HZQBy4q9r5SEzNGNIoFClT43HPNDbUdHH-GYNYYdkRfft6XptJBkUQscZsGxOW975Yk6RbgtGvq1nkEcklOw"
+   }
+   ```
+
+   `CLIENT_SECRET` 是生成给应用程序的唯一密钥。请注意，该密钥只会在您使用 Gitea 创建/注册应用程序后出现一次。如果您丢失了密钥，您必须在应用程序设置中重新生成密钥。
+
+   `access_token` 请求中的 `REDIRECT_URI` 必须与 `authorize` 请求中的 `REDIRECT_URI` 相符。
+
+3. 使用 `access_token` 来构造 [API 请求](development/api-usage.md#oauth2-provider) 以读写用户的资源。
diff --git a/docs/document/help/faq.md b/docs/document/help/faq.md
new file mode 100644
index 0000000..e99bb62
--- /dev/null
+++ b/docs/document/help/faq.md
@@ -0,0 +1,433 @@
+---
+date: "2023-05-25T16:00:00+02:00"
+slug: "faq"
+sidebar_position: 5
+aliases:
+  - /zh-cn/faq
+---
+
+# 常见问题
+
+本页面包含一些常见问题和答案。
+
+有关更多帮助资源，请查看所有[支持选项](help/support.md)。
+
+## 1.x 和 1.x.x 下载之间的区别
+
+以 1.7.x 版本为例。
+
+**注意：**此示例也适用于 Docker 镜像！
+
+在我们的[下载页面](https://dl.gitea.com/gitea/)上，您会看到一个 1.7 目录，以及 1.7.0、1.7.1、1.7.2、1.7.3、1.7.4、1.7.5 和 1.7.6 的目录。
+
+1.7 目录和 1.7.0 目录是**不同**的。1.7 目录是在每个合并到[`release/v1.7`](https://github.com/go-gitea/gitea/tree/release/v1.7)分支的提交上构建的。
+
+然而，1.7.0 目录是在创建[`v1.7.0`](https://github.com/go-gitea/gitea/releases/tag/v1.7.0)标签时创建的构建。
+
+这意味着 1.x 的下载会随着提交合并到各自的分支而改变（将其视为每个版本的单独的“main”分支）。
+
+另一方面，1.x.x 的下载应该永远不会改变。
+
+## 如何从 Gogs/GitHub 等迁移到 Gitea
+
+要从 Gogs 迁移到 Gitea：
+
+- [Gogs 版本 0.11.46.0418](https://github.com/go-gitea/gitea/issues/4286)
+
+要从 GitHub 迁移到 Gitea，您可以使用 Gitea 内置的迁移表单。
+
+为了迁移诸如问题、拉取请求等项目，您需要至少输入您的用户名。
+
+[Example (requires login)](https://demo.gitea.com/repo/migrate)
+
+要从 GitLab 迁移到 Gitea，您可以使用这个非关联的工具：
+
+https://github.com/loganinak/MigrateGitlabToGogs
+
+## Gitea 存储文件的位置
+
+- _`AppWorkPath`_
+  - `--work-path`标志
+  - 或者环境变量`GITEA_WORK_DIR`
+  - 或者在构建时设置的内置值
+  - 或者包含 Gitea 二进制文件的目录
+- `%(APP_DATA_PATH)`（数据库、索引器等的默认路径）
+  - `app.ini`中的`APP_DATA_PATH`
+  - 或者*`AppWorkPath`*`/data`
+- _`CustomPath`_（自定义模板）
+  - `--custom-path`标志
+  - 或者环境变量`GITEA_CUSTOM`
+  - 或者在构建时设置的内置值
+  - 或者*`AppWorkPath`*`/custom`
+- HomeDir
+  - Unix：环境变量`HOME`
+  - Windows：环境变量`USERPROFILE`，或者环境变量`HOMEDRIVE`+`HOMEPATH`
+- RepoRootPath
+  - `app.ini`中\[repository]部分的`ROOT`（如果是绝对路径）
+  - 否则*`AppWorkPath`*`/ROOT`(如果`app.ini`中\[repository]部分的`ROOT`是相对路径）
+  - 默认值为`%(APP_DATA_PATH)/gitea-repositories`
+- INI（配置文件）
+  - `--config`标志
+  - 或者在构建时设置的可能内置值
+  - 或者 _`CustomPath`_`/conf/app.ini`
+- SQLite 数据库
+  - app.ini 中 database 部分的 PATH
+  - 或者`%(APP_DATA_PATH)/gitea.db`
+
+## 看不到克隆 URL 或克隆 URL 不正确
+
+有几个地方可能会导致显示不正确。
+
+1. 如果使用反向代理，请确保按照[反向代理指南](../administration/reverse-proxies.md)中的正确说明进行设置。
+2. 确保在`app.ini`的`server`部分中正确设置了`ROOT_URL`。
+
+如果某些克隆选项未显示（HTTP/S 或 SSH），可以在`app.ini中`
+
+- `DISABLE_HTTP_GIT`: 如果设为 true, 将会没有 HTTP/HTTPS 链接
+- `DISABLE_SSH`: 如果设为 true, 将会没有 SSH 链接
+- `SSH_EXPOSE_ANONYMOUS`: 如果设为 false, SSH 链接将会对匿名用户隐藏
+
+## 文件上传失败：413 Request Entity Too Large
+
+当反向代理限制文件上传大小时，会出现此错误。
+
+有关使用 nginx 解决此问题，请参阅[反向代理指南](../administration/reverse-proxies.md)。
+
+## 自定义模板无法加载或运行错误
+
+Gitea 的自定义模板必须将其添加到正确的位置，否则 Gitea 将无法找到并使用自定义模板。
+
+模板的正确路径应该相对于`CustomPath`。
+
+1. 要找到`CustomPath`，请在站点管理 -> 配置 中查找自定义文件根路径。
+
+   如果找不到，请尝试`echo $GITEA_CUSTOM`。
+
+2. 如果仍然找不到，默认值可以被[计算](faq.md#Gitea存储文件的位置)
+3. 如果仍然找不到路径，则可以参考[自定义 Gitea](../administration/customizing-gitea.md)页面，将模板添加到正确的位置。
+
+## Gitea 是否有"GitHub/GitLab Pages"功能？
+
+Gitea 不提供内置的 Pages 服务器。您需要一个专用的域名来提供静态页面，以避免 CSRF 安全风险。
+
+对于简单的用法，您可以使用反向代理来重写和提供 Gitea 的原始文件 URL 中的静态内容。
+
+还有一些已经可用的第三方服务，比如独立[pages server](https://codeberg.org/Codeberg/pages-server)的或[caddy plugin](https://github.com/42wim/caddy-gitea)，可以提供所需的功能。
+
+## 活跃用户与禁止登录用户
+
+在 Gitea 中，"活跃用户"是指通过电子邮件激活其帐户的用户。
+
+"禁止登录用户"是指不允许再登录到 Gitea 的用户。
+
+## 设置日志记录
+
+- [官方文档](../administration/logging-config.md)
+
+## 什么是 Swagger？
+
+[Swagger](https://swagger.io/) 是 Gitea 用于其 API 文档的工具。
+
+所有 Gitea 实例都有内置的 API，无法完全禁用它。
+但是，您可以在 app.ini 的 api 部分将 ENABLE_SWAGGER 设置为 false，以禁用其文档显示。
+有关更多信息，请参阅 Gitea 的[API 文档](development/api-usage.md)。
+
+您可以在上查看最新的 API（例如）https://gitea.com/api/swagger
+
+您还可以在上查看`swagger.json`文件的示例 https://gitea.com/swagger.v1.json
+
+## 调整服务器用于公共/私有使用
+
+### 防止垃圾邮件发送者
+
+有多种方法可以组合使用来防止垃圾邮件发送者：
+
+1. 通过设置电子邮件域名的白名单或黑名单。
+2. 通过设置一些域名或者 OpenID 白名单（见下文）。
+3. 在您的`app.ini`中将`ENABLE_CAPTCHA`设置为`true`，并正确配置`RECAPTCHA_SECRET`和 `RECAPTCHA_SITEKEY`。
+4. 将`DISABLE_REGISTRATION`设置为`true`，并通过 [CLI](../administration/command-line.md)、[API](development/api-usage.md) 或 Gitea 的管理界面创建新用户。
+
+### 仅允许/阻止特定的电子邮件域名
+
+您可以在`app.ini`中的`[service]`下的配置`EMAIL_DOMAIN_WHITELIST` 或 `EMAIL_DOMAIN_BLOCKLIST`。
+
+### 仅允许/阻止特定的 OpenID 提供商
+
+您可以在`app.ini`的`[openid]`下配置`WHITELISTED_URI`或`BLACKLISTED_URIS`。
+
+**注意**： 白名单优先，如果白名单非空，则忽略黑名单。
+
+### 仅允许发布问题的用户
+
+目前实现这一点的方法是创建/修改一个具有最大仓库创建限制为 0 的用户。
+
+### 受限制的用户
+
+受限制的用户仅能访问其组织/团队成员和协作所在的内容的子集，而忽略组织/仓库等的公共标志。
+
+示例用例：一个公司运行一个需要登录的 Gitea 实例。大多数仓库是公开的（所有同事都可以访问/浏览）。
+
+在某些情况下，某个客户或第三方需要访问特定的仓库，并且只能访问该仓库。通过将此类客户帐户设置为受限制帐户，并使用团队成员身份和/或协作来授予所需的任何访问权限，可以简单地实现这一点，而无需使所有内容都变为私有。
+
+### 启用 Fail2ban
+
+使用 [Fail2Ban](../administration/fail2ban-setup.md) 监视并阻止基于日志模式的自动登录尝试或其他恶意行为。
+
+## SSHD vs 内建 SSH
+
+SSHD 是大多数 Unix 系统上内建的 SSH 服务器。
+
+Gitea 还提供了自己的 SSH 服务器，用于在 SSHD 不可用时使用。
+
+## Gitea 运行缓慢
+
+导致此问题的最常见原因是加载联合头像。
+
+您可以通过在`app.ini`中将`ENABLE_FEDERATED_AVATAR`设置为`false`来关闭此功能。
+
+还有一个可能需要更改的选项是在`app.ini`中将`DISABLE_GRAVATAR`设置为`true`。
+
+## 无法创建仓库/文件
+
+请确保 Gitea 具有足够的权限来写入其主目录和数据目录。
+
+参见[AppDataPath 和 RepoRootPath](faq.md#Gitea存储文件的位置)
+
+**适用于 Arch 用户的注意事项：**在撰写本文时，Arch 软件包的 systemd 文件包含了以下行：
+
+`ReadWritePaths=/etc/gitea/app.ini`
+
+这将使得 Gitea 无法写入其他路径。
+
+## 翻译不正确/如何添加更多翻译
+
+我们当前的翻译是在我们的[Crowdin 项目](https://crowdin.com/project/gitea)上众包进行的
+
+无论您想要更改翻译还是添加新的翻译，都需要在 Crowdin 集成中进行，因为所有翻译都会被 CI 覆盖。
+
+## 推送钩子/ Webhook / Actions 未运行
+
+如果您可以推送但无法在主页仪表板上看到推送活动，或者推送不触发 Webhook 和 Actions，可能是 git 钩子不工作而导致的。
+
+这可能是由于以下原因：
+
+1. Git 钩子不同步：在站点管理面板上运行“重新同步所有仓库的 pre-receive、update 和 post-receive 钩子”
+2. Git 仓库（和钩子）存储在一些不支持脚本执行的文件系统上（例如由 NAS 挂载），请确保文件系统支持`chmod a+x any-script`
+3. 如果您使用的是 Docker，请确保 Docker Server（而不是客户端）的版本 >= 20.10.6
+
+## SSH 问题
+
+如果无法通过`ssh`访问仓库，但`https`正常工作，请考虑以下情况。
+
+首先，请确保您可以通过 SSH 访问 Gitea。
+
+`ssh git@myremote.example`
+
+如果连接成功，您应该会收到以下错误消息：
+
+```
+Hi there, You've successfully authenticated, but Gitea does not provide shell access.
+If this is unexpected, please log in with password and setup Gitea under another user.
+```
+
+如果您收到以上消息但仍然连接成功，这意味着您的 SSH 密钥**没有**由 Gitea 管理。这意味着钩子不会运行，在其他一些潜在问题中也包括在内。
+
+如果您无法连接，可能是因为您的 SSH 密钥在本地配置不正确。
+这是针对 SSH 而不是 Gitea 的问题，因此在此不涉及。
+
+### SSH 常见错误
+
+```
+Permission denied (publickey).
+fatal: Could not read from remote repository.
+```
+
+此错误表示服务器拒绝登录尝试，
+请检查以下事项：
+
+- 在客户端：
+  - 确保公钥和私钥已添加到正确的 Gitea 用户。
+  - 确保远程 URL 中没有任何问题。特别是，请确保 ∂
+    Git 用户（@ 之前的部分）的名称拼写正确。
+  - 确保客户端机器上的公钥和私钥正确无误。
+- 在服务器上：
+
+  - 确保存储库存在并且命名正确。
+  - 检查系统用户主目录中的 `.ssh` 目录的权限。
+  - 验证正确的公钥是否已添加到 `.ssh/authorized_keys` 中。
+
+  尝试在 Gitea 管理面板上运行
+  `Rewrite '.ssh/authorized_keys' file (for Gitea SSH keys)`。
+
+- 查看 Gitea 日志。
+- 查看 /var/log/auth（或类似的文件）。
+- 检查存储库的权限。
+
+以下是一个示例，其中缺少公共 SSH 密钥，
+认证成功，但是其他设置导致 SSH 无法访问正确的
+存储库。
+
+```
+fatal: Could not read from remote repository.
+
+Please make sure you have the correct access rights
+and the repository exists.
+```
+
+在这种情况下，请检查以下设置：
+
+- 在服务器上：
+  - 确保`git`系统用户设置了可用的 shell
+    - 使用`getent passwd git | cut -d: -f7`进行验证
+    - 可以使用`usermod`或`chsh`进行修改。
+  - 确保`.ssh/authorized_keys`中的`gitea serv`命令使用
+    正确的配置文件。
+
+## 迁移带有标签的存储库后缺失发布版本
+
+要迁移带有所有标签的存储库，您需要执行两个操作：
+
+- 推送标签到存储库：
+
+```
+ git push --tags
+```
+
+- 在 Gitea 中重新同步所有存储库的标签：
+
+```
+gitea admin repo-sync-releases
+```
+
+## LFS 问题
+
+针对涉及 LFS 数据上传的问题
+
+```
+batch response: Authentication required: Authorization error: <GITEA_LFS_URL>/info/lfs/objects/batch
+Check that you have proper access to the repository
+error: failed to push some refs to '<GIT_REPO_URL>'
+```
+
+检查`app.ini`文件中的`LFS_HTTP_AUTH_EXPIRY`值。
+
+默认情况下，LFS 令牌在 20 分钟后过期。如果您的连接速度较慢或文件较大（或两者都是），可能无法在时间限制内完成上传。
+
+您可以将此值设置为`60m`或`120m`。
+
+## 如何在启动 Gitea 之前创建用户
+
+Gitea 提供了一个子命令`gitea migrate`来初始化数据库，然后您可以使用[管理 CLI 命令](../administration/command-line.md#admin)像正常情况下添加用户。
+
+## 如何启用密码重置
+
+没有密码重置的设置。当配置了[邮件服务](../administration/email-setup.md)时，密码重置将自动启用；否则将被禁用。
+
+## 如何更改用户的密码
+
+- 作为管理员，您可以更改任何用户的密码（并可选择强制其在下次登录时更改密码）...
+  - 转到您的`站点管理 -> 用户账户`页面并编辑用户。
+- 使用[管理 CLI 命令](../administration/command-line.md#admin)。
+
+  请注意，大多数命令还需要一个[全局标志](../administration/command-line.md#全局选项)来指向正确的配置。
+
+- 作为**用户**，您可以更改密码...
+
+  - 在您的账户的`设置 -> 账户`页面（此方法**需要**您知道当前密码）。
+  - 使用`忘记密码`链接。
+
+  如果`忘记密码/账户恢复`页面被禁用，请联系管理员配置[邮件服务](../administration/email-setup.md)。
+
+## 为什么我的 Markdown 显示错误
+
+在 Gitea 版本 `1.11` 中，我们转换为使用[goldmark](https://github.com/yuin/goldmark)进行 Markdown 渲染，它符合[CommonMark](https://commonmark.org/)标准。
+
+如果您在版本`1.11`之前的 Markdown 正常工作，但在升级后无法正常工作，请仔细阅读 CommonMark 规范，看看问题是由错误还是非兼容的语法引起的。
+
+如果是后者，通常规范中会列出一种符合标准的替代方法。
+
+## 使用 MySQL 进行升级时出现的错误
+
+如果在使用 MySQL 升级 Gitea 时收到以下错误：
+
+> `ORM engine initialization failed: migrate: do migrate: Error: 1118: Row size too large...`
+
+请运行 `gitea doctor convert` 或对数据库中的每个表运行 `ALTER TABLE table_name ROW_FORMAT=dynamic;`。
+
+潜在问题是默认行格式分配给每个表的索引空间
+太小。Gitea 要求其表的`ROWFORMAT`为`DYNAMIC`。
+
+如果收到包含`Error 1071: Specified key was too long; max key length is 1000 bytes...`
+的错误行，则表示您正在尝试在使用 ISAM 引擎的表上运行 Gitea。尽管在先前版本的 Gitea 中可能是凑巧能够工作的，但它从未得到官方支持，
+您必须使用 InnoDB。您应该对数据库中的每个表运行`ALTER TABLE table_name ENGINE=InnoDB;`。
+
+## 为什么 Emoji 只显示占位符或单色图像
+
+Gitea 需要系统或浏览器安装其中一个受支持的 Emoji 字体，例如 Apple Color Emoji、Segoe UI Emoji、Segoe UI Symbol、Noto Color Emoji 和 Twemoji Mozilla。通常，操作系统应该已经提供了其中一个字体，但特别是在 Linux 上，可能需要手动安装它们。
+
+## SystemD 和 Docker 上的标准输出日志
+
+SystemD 上的标准输出默认会写入日志记录中。您可以尝试使用 `journalctl`、`journalctl -u gitea` 或 `journalctl <path-to-gitea-binary>`来查看。
+
+类似地，Docker 上的标准输出可以使用`docker logs <container>`来查看。
+
+要收集日志以进行帮助和问题报告，请参阅[支持选项](help/support.md)。
+
+## 初始日志记录
+
+在 Gitea 读取配置文件并设置其日志记录之前，它会将一些内容记录到标准输出，以帮助调试日志记录无法工作的情况。
+
+您可以通过设置`--quiet`或`-q`选项来停止此日志记录。请注意，这只会在 Gitea 设置自己的日志记录之前停止日志记录。
+
+如果您报告了错误或问题，必须提供这些信息以恢复初始日志记录。
+
+只有在完全配置了所有内容之后，您才应该设置此选项。
+
+## 在数据库启动期间出现有关结构默认值的警告
+
+有时，在迁移过程中，旧列和默认值可能在数据库架构中保持不变。
+这可能会导致警告，例如：
+
+```
+2020/08/02 11:32:29 ...rm/session_schema.go:360:Sync() [W] Table user Column keep_activity_private db default is , struct default is 0
+```
+
+可以安全地忽略这些警告，但您可以通过让 Gitea 重新创建这些表来停止这些警告，使用以下命令：
+
+```
+gitea doctor recreate-table user
+```
+
+这将导致 Gitea 重新创建用户表并将旧数据复制到新表中，
+并正确设置默认值。
+
+您可以使用以下命令要求 Gitea 重新创建多个表：
+
+```
+gitea doctor recreate-table table1 table2 ...
+```
+
+如果您希望 Gitea 重新创建所有表，请使用以下命令：
+
+```
+gitea doctor recreate-table
+```
+
+在运行这些命令之前，强烈建议您备份数据库。
+
+## 为什么查看文件时制表符/缩进显示错误
+
+如果您正在使用 Cloudflare，请在仪表板中关闭自动缩小选项。
+
+`Speed` -> `Optimization` -> 在 `Auto-Minify` 设置中取消选中 `HTML`。
+
+## 如何从磁盘采用存储库
+
+- 将您的（裸）存储库添加到正确的位置，即您的配置所在的地方（`repository.ROOT`），确保它们位于正确的布局`<REPO_ROOT>/[user]/[repo].git`。
+  - **注意：**目录名必须为小写。
+  - 您还可以在`<ROOT_URL>/admin/config`中检查存储库根路径。
+- 确保存在要采用存储库的用户/组织。
+- 作为管理员，转到`<ROOT_URL>/admin/repos/unadopted`并搜索。
+- 用户也可以通过配置[`ALLOW_ADOPTION_OF_UNADOPTED_REPOSITORIES`](../administration/config-cheat-sheet.md#仓库) 获得类似的权限。
+- 如果上述步骤都正确执行，您应该能够选择要采用的存储库。
+  - 如果没有找到存储库，请启用[调试日志记录](../administration/config-cheat-sheet.md#仓库)以检查是否有特定错误。
diff --git a/docs/document/help/support.md b/docs/document/help/support.md
new file mode 100644
index 0000000..b191f7c
--- /dev/null
+++ b/docs/document/help/support.md
@@ -0,0 +1,69 @@
+---
+date: "2017-01-20T15:00:00+08:00"
+slug: "support"
+sidebar_position: 20
+aliases:
+  - /zh-cn/seek-help
+---
+
+# 支持选项
+
+- [付费商业支持](https://about.gitea.com/)
+- [Discord](https://discord.gg/Gitea)
+- [论坛](https://forum.gitea.com/)
+- [Matrix](https://matrix.to/#/#gitea-space:matrix.org)
+  - 注意：大多数 Matrix 频道都与 Discord 中的对应频道桥接，可能在桥接过程中会出现一定程度的不稳定性。
+- 中文支持
+  - [Discourse 中文分类](https://forum.gitea.com/c/5-category/5)
+  - QQ 群 328432459
+
+# Bug 报告
+
+如果您发现了 Bug，请在 GitHub 上 [创建一个问题](https://github.com/go-gitea/gitea/issues)。
+
+**注意：** 在请求支持时，可能需要准备以下信息，以便帮助者获得所需的所有信息：
+
+1. 您的 `app.ini`（将任何敏感数据进行必要的清除）。
+2. 您看到的任何错误消息。
+3. Gitea 日志以及与情况相关的所有其他日志。
+   - 收集 `trace` / `debug` 级别的日志更有用（参见下一节）。
+   - 在使用 systemd 时，使用 `journalctl --lines 1000 --unit gitea` 收集日志。
+   - 在使用 Docker 时，使用 `docker logs --tail 1000 <gitea-container>` 收集日志。
+4. 可重现的步骤，以便他人能够更快速、更容易地重现和理解问题。
+   - [demo.gitea.com](https://demo.gitea.com) 可用于重现问题。
+5. 如果遇到慢速/挂起/死锁等问题，请在出现问题时报告堆栈跟踪。
+   转到 "Site Admin" -> "Monitoring" -> "Stacktrace" -> "Download diagnosis report"。
+
+# 高级 Bug 报告提示
+
+## 更多日志的配置选项
+
+默认情况下，日志以 `info` 级别输出到控制台。
+如果您需要设置日志级别和/或从文件中收集日志，
+您只需将以下配置复制到您的 `app.ini` 中（删除所有其他 `[log]` 部分），
+然后您将在 Gitea 的日志目录中找到 `*.log` 文件（默认为 `%(GITEA_WORK_DIR)/log`）。
+
+```ini
+; 要显示所有 SQL 日志，您还可以在 [database] 部分中设置 LOG_SQL=true
+[log]
+LEVEL=debug
+MODE=console,file
+```
+
+## 使用命令行收集堆栈跟踪
+
+Gitea 可以使用 Golang 的 pprof 处理程序和工具链来收集堆栈跟踪和其他运行时信息。
+
+如果 Web UI 停止工作，您可以尝试通过命令行收集堆栈跟踪：
+
+1. 设置 app.ini：
+
+   ```
+   [server]
+   ENABLE_PPROF = true
+   ```
+
+2. 重新启动 Gitea
+
+3. 尝试触发 bug，当请求卡住一段时间，使用或浏览器访问：获取堆栈跟踪。
+   `curl http://127.0.0.1:6060/debug/pprof/goroutine?debug=1`
diff --git a/docs/document/usage/actions/act-runner.md b/docs/document/usage/actions/act-runner.md
new file mode 100644
index 0000000..5d9f1aa
--- /dev/null
+++ b/docs/document/usage/actions/act-runner.md
@@ -0,0 +1,267 @@
+---
+date: "2023-05-24T15:00:00+08:00"
+slug: "act-runner"
+sidebar_position: 20
+---
+
+# Act Runner
+
+本页面将详细介绍[Act Runner](https://gitea.com/gitea/act_runner)，这是Gitea Actions的Runner。
+
+## 要求
+
+建议在Docker容器中运行Job，因此您需要首先安装Docker。
+并确保Docker守护进程正在运行。
+
+其他与Docker API兼容的OCI容器引擎也应该可以正常工作，但尚未经过测试。
+
+但是，如果您确定要直接在主机上运行Job，则不需要Docker。
+
+## 安装
+
+有多种安装Act Runner的方法。
+
+### 下载二进制文件
+
+您可以从[发布页面](https://gitea.com/gitea/act_runner/releases)下载二进制文件。
+然而，如果您想使用最新的夜间构建版本，可以从[下载页面](https://dl.gitea.com/act_runner/)下载。
+
+下载二进制文件时，请确保您已经下载了适用于您的平台的正确版本。
+您可以通过运行以下命令进行检查：
+
+```bash
+chmod +x act_runner
+./act_runner --version
+```
+
+如果看到版本信息，则表示您已经下载了正确的二进制文件。
+
+### 使用 Docker 镜像
+
+您可以使用[docker hub](https://hub.docker.com/r/gitea/act_runner/tags)上的Docker镜像。
+与二进制文件类似，您可以使用`nightly`标签使用最新的夜间构建版本，而`latest`标签是最新的稳定版本。
+
+```bash
+docker pull docker.io/gitea/act_runner:latest # for the latest stable release
+docker pull docker.io/gitea/act_runner:nightly # for the latest nightly build
+```
+
+## 配置
+
+配置通过配置文件进行。它是可选的，当没有指定配置文件时，将使用默认配置。
+
+您可以通过运行以下命令生成配置文件：
+
+```bash
+./act_runner generate-config
+```
+
+默认配置是安全的，可以直接使用。
+
+```bash
+./act_runner generate-config > config.yaml
+./act_runner --config config.yaml [command]
+```
+
+您亦可以如下使用 docker 创建配置文件：
+
+```bash
+docker run --entrypoint="" --rm -it docker.io/gitea/act_runner:latest act_runner generate-config > config.yaml
+```
+
+当使用Docker镜像时，可以使用`CONFIG_FILE`环境变量指定配置文件。确保将文件作为卷挂载到容器中：
+
+```bash
+docker run -v $(pwd)/config.yaml:/config.yaml -e CONFIG_FILE=/config.yaml ...
+```
+
+您可能注意到上面的命令都是不完整的，因为现在还不是运行Act Runner的时候。
+在运行Act Runner之前，我们需要首先将其注册到您的Gitea实例中。
+
+## 注册
+
+在运行Act Runner之前，需要进行注册，因为Runner需要知道从哪里获取Job，并且对于Gitea实例来说，识别Runner也很重要。
+
+### Runner级别
+
+您可以在不同级别上注册Runner，它可以是：
+
+- 实例级别：Runner将为实例中的所有存储库运行Job。
+- 组织级别：Runner将为组织中的所有存储库运行Job。
+- 存储库级别：Runner将为其所属的存储库运行Job。
+
+请注意，即使存储库具有自己的存储库级别Runner，它仍然可以使用实例级别或组织级别Runner。未来的版本可能提供更多对此进行更好控制的选项。
+
+### 获取注册令牌
+
+Runner级别决定了从哪里获取注册令牌。
+
+- 实例级别：管理员设置页面，例如 `<your_gitea.com>/admin/actions/runners`。
+- 组织级别：组织设置页面，例如 `<your_gitea.com>/<org>/settings/actions/runners`。
+- 存储库级别：存储库设置页面，例如 `<your_gitea.com>/<owner>/<repo>/settings/actions/runners`。
+
+如果您无法看到设置页面，请确保您具有正确的权限并且已启用 Actions。
+
+注册令牌的格式是一个随机字符串 `D0gvfu2iHfUjNqCYVljVyRV14fISpJxxxxxxxxxx`。
+
+注册令牌也可以通过 Gitea 的 [命令行](../../administration/command-line.md#actions-generate-runner-token) 获得:
+
+```
+gitea --config /etc/gitea/app.ini actions generate-runner-token
+```
+
+用户也可以使用 `GITEA_RUNNER_REGISTRATION_TOKEN` 或 `GITEA_RUNNER_REGISTRATION_TOKEN_FILE` 环境变量以在 Gitea 启动时设置全局的注册令牌，例如：
+
+```
+openssl rand -hex 24 > /some-dir/runner-token
+export GITEA_RUNNER_REGISTRATION_TOKEN_FILE=/some-dir/runner-token
+./gitea --config ...
+```
+
+来自环境变量的令牌在通过 Web 界面或 API 重置(重新创建新令牌)前将一直有效。
+
+令牌可用于注册多个 Runner，直到使用 Web 界面中的令牌重置链接将其撤销并替换为新令牌。
+
+### 注册Runner
+
+可以通过运行以下命令来注册Act Runner：
+
+```bash
+./act_runner register
+```
+
+或者，您可以使用 `--config` 选项来指定前面部分提到的配置文件。
+
+```bash
+./act_runner --config config.yaml register
+```
+
+您将逐步输入注册信息，包括：
+
+- Gitea 实例的 URL，例如 `https://gitea.com/` 或 `http://192.168.8.8:3000/`。
+- 注册令牌。
+- Runner名称（可选）。如果留空，将使用主机名。
+- Runner标签（可选）。如果留空，将使用默认标签。
+
+您可能对Runner标签感到困惑，稍后将对其进行解释。
+
+如果您想以非交互方式注册Runner，可以使用参数执行以下操作。
+
+```bash
+./act_runner register --no-interactive --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_labels>
+```
+
+注册Runner后，您可以在当前目录中找到一个名为 `.runner` 的新文件。该文件存储注册信息。
+请不要手动编辑该文件。
+如果此文件丢失或损坏，可以直接删除它并重新注册。
+
+如果您想将注册信息存储在其他位置，请在配置文件中指定，并不要忘记指定 `--config` 选项。
+
+### 使用Docker注册Runner
+
+如果您使用的是Docker镜像，注册行为会略有不同。在这种情况下，注册和运行合并为一步，因此您需要在运行Act Runner时指定注册信息。
+
+```bash
+docker run \
+    -v $(pwd)/config.yaml:/config.yaml \
+    -v $(pwd)/data:/data \
+    -v /var/run/docker.sock:/var/run/docker.sock \
+    -e CONFIG_FILE=/config.yaml \
+    -e GITEA_INSTANCE_URL=<instance_url> \
+    -e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \
+    -e GITEA_RUNNER_NAME=<runner_name> \
+    -e GITEA_RUNNER_LABELS=<runner_labels> \
+    --name my_runner \
+    -d gitea/act_runner:nightly
+```
+
+您可能注意到我们已将`/var/run/docker.sock`挂载到容器中。
+这是因为Act Runner将在Docker容器中运行Job，因此它需要与Docker守护进程进行通信。
+如前所述，如果要在主机上直接运行Job，可以将其移除。
+需要明确的是，这里的 "主机" 实际上指的是当前运行 Act Runner的容器，而不是主机机器本身。
+
+### 使用 Docker compose 运行 Runner
+
+您亦可使用如下的 `docker-compose.yml`:
+
+```yml
+version: "3.8"
+services:
+  runner:
+    image: gitea/act_runner:nightly
+    environment:
+      CONFIG_FILE: /config.yaml
+      GITEA_INSTANCE_URL: "${INSTANCE_URL}"
+      GITEA_RUNNER_REGISTRATION_TOKEN: "${REGISTRATION_TOKEN}"
+      GITEA_RUNNER_NAME: "${RUNNER_NAME}"
+      GITEA_RUNNER_LABELS: "${RUNNER_LABELS}"
+    volumes:
+      - ./config.yaml:/config.yaml
+      - ./data:/data
+      - /var/run/docker.sock:/var/run/docker.sock
+```
+
+### 当您使用 Docker 镜像启动 Runner，如何配置 Cache
+
+如果你不打算在工作流中使用 `actions/cache`，你可以忽略本段。
+
+如果您在使用 `actions/cache` 时没有进行额外的配置，将会返回以下错误信息：
+> Failed to restore: getCacheEntry failed: connect ETIMEDOUT IP:PORT
+
+这个错误的原因是 runner 容器和作业容器位于不同的网络中，因此作业容器无法访问 runner 容器。
+因此，配置 cache 动作以确保其正常运行是非常重要的。请按照以下步骤操作：
+
+- 1.获取 Runner 容器所在主机的 LAN（本地局域网） IP 地址。
+- 2.获取一个 Runner 容器所在主机的空闲端口号。
+- 3.在配置文件中如下配置：
+
+```yaml
+cache:
+  enabled: true
+  dir: ""
+  # 使用步骤 1. 获取的 LAN IP
+  host: "192.168.8.17"
+  # 使用步骤 2. 获取的端口号
+  port: 8088
+```
+
+- 4.启动容器时, 将 Cache 端口映射至主机。
+
+```bash
+docker run \
+  --name gitea-docker-runner \
+  -p 8088:8088 \
+  -d gitea/act_runner:nightly
+```
+
+### 标签
+
+Runner的标签用于确定Runner可以运行哪些Job以及如何运行它们。
+
+默认标签为`ubuntu-latest:docker://node:16-bullseye,ubuntu-22.04:docker://node:16-bullseye,ubuntu-20.04:docker://node:16-bullseye,ubuntu-18.04:docker://node:16-buster`。
+它们是逗号分隔的列表，每个项目都是一个标签。
+
+让我们以 `ubuntu-22.04:docker://node:16-bullseye` 为例。
+它意味着Runner可以运行带有`runs-on: ubuntu-22.04`的Job，并且该Job将在使用`node:16-bullseye`镜像的Docker容器中运行。
+
+如果默认镜像无法满足您的需求，并且您有足够的磁盘空间可以使用更好、更大的镜像，您可以将其更改为`ubuntu-22.04:docker://<您喜欢的镜像>`。
+您可以在[act 镜像](https://github.com/nektos/act/blob/master/IMAGES.md)上找到更多有用的镜像。
+
+如果您想直接在主机上运行Job，您可以将其更改为`ubuntu-22.04:host`或仅`ubuntu-22.04`，`:host`是可选的。
+然而，我们建议您使用类似`linux_amd64:host`或`windows:host`的特殊名称，以避免误用。
+
+从 Gitea 1.21 开始，您可以通过修改 runner 的配置文件中的 `container.labels` 来更改标签（如果没有配置文件，请参考 [配置教程](#配置)），通过执行 `./act_runner daemon --config config.yaml` 命令重启 runner 之后，这些新定义的标签就会生效。
+
+## 运行
+
+注册完Runner后，您可以通过运行以下命令来运行它：
+
+```bash
+./act_runner daemon
+# or
+./act_runner daemon --config config.yaml
+```
+
+Runner将从Gitea实例获取Job并自动运行它们。
+
+由于Act Runner仍处于开发中，建议定期检查最新版本并进行升级。
diff --git a/docs/document/usage/actions/badge.md b/docs/document/usage/actions/badge.md
new file mode 100644
index 0000000..86b4500
--- /dev/null
+++ b/docs/document/usage/actions/badge.md
@@ -0,0 +1,27 @@
+---
+date: "2023-02-25T00:00:00+00:00"
+slug: "badge"
+sidebar_position: 110
+---
+
+# Badge
+
+Gitea has its builtin Badge system which allows you to display the status of your repository in other places. You can use the following badges:
+
+## Workflow Badge
+
+The Gitea Actions workflow badge is a badge that shows the status of the latest workflow run.
+It is designed to be compatible with [GitHub Actions workflow badge](https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/adding-a-workflow-status-badge).
+
+You can use the following URL to get the badge:
+
+```
+https://your-gitea-instance.com/{owner}/{repo}/actions/workflows/{workflow_file}/badge.svg?branch={branch}&event={event}&style={style}
+```
+
+- `{owner}`: The owner of the repository.
+- `{repo}`: The name of the repository.
+- `{workflow_file}`: The name of the workflow file.
+- `{branch}`: Optional. The branch of the workflow. Default to your repository's default branch.
+- `{event}`: Optional. The event of the workflow. Default to none.
+- `{style}`: Optional. Style of the badge, either `flat` or `flat-square`. Default to `flat`.
diff --git a/docs/document/usage/actions/comparison.md b/docs/document/usage/actions/comparison.md
new file mode 100644
index 0000000..5601c54
--- /dev/null
+++ b/docs/document/usage/actions/comparison.md
@@ -0,0 +1,125 @@
+---
+date: "2023-05-24T15:00:00+08:00"
+slug: "comparison"
+sidebar_position: 15
+---
+
+# 与GitHub Actions的对比
+
+尽管Gitea Actions旨在与GitHub Actions兼容，但它们之间存在一些差异。
+
+## 额外功能
+
+### Action URL绝对路径
+
+Gitea Actions支持通过URL绝对路径定义actions，这意味着您可以使用来自任何Git存储库的Actions。
+例如，`uses: https://github.com/actions/checkout@v4`或`uses: http://your_gitea.com/owner/repo@branch`。
+
+### 使用Go编写Actions
+
+Gitea Actions支持使用Go编写Actions。
+请参阅[创建Go Actions](https://blog.gitea.com/creating-go-actions/)。
+
+### 支持非标准的调度语法 @yearly, @monthly, @weekly, @daily, @hourly
+
+Github Actions 不支持这些语法，详见： https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule
+
+## 不支持的工作流语法
+
+### `concurrency`
+
+这是用于一次运行一个Job。
+请参阅[使用并发](https://docs.github.com/zh/actions/using-jobs/using-concurrency)。
+
+Gitea Actions目前不支持此功能。
+
+### `run-name`
+
+这是工作流生成的工作流运行的名称。
+请参阅[GitHub Actions 的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#run-name)。
+
+Gitea Actions目前不支持此功能。
+
+### `permissions`和`jobs.<job_id>.permissions`
+
+请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#permissions)。
+
+Gitea Actions目前不支持此功能。
+
+### `jobs.<job_id>.timeout-minutes`
+
+请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes)。
+
+Gitea Actions目前不支持此功能。
+
+### `jobs.<job_id>.continue-on-error`
+
+请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idcontinue-on-error)。
+
+Gitea Actions目前不支持此功能。
+
+### `jobs.<job_id>.environment`
+
+请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment)。
+
+Gitea Actions 目前不支持此功能。
+
+### 复杂的`runs-on`
+
+请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)。
+
+Gitea Actions目前只支持`runs-on: xyz`或`runs-on: [xyz]`。
+
+### `hashFiles`表达式
+
+请参阅[表达式](https://docs.github.com/en/actions/learn-github-actions/expressions#hashfiles)。
+
+Gitea Actions目前不支持此功能，如果使用它，结果将始终为空字符串。
+
+作为解决方法，您可以使用[go-hashfiles](https://gitea.com/actions/go-hashfiles)。
+
+## 缺失的功能
+
+### 问题匹配器
+
+问题匹配器是一种扫描Actions输出以查找指定正则表达式模式并在用户界面中突出显示该信息的方法。
+请参阅[问题匹配器](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md)。
+
+Gitea Actions目前不支持此功能。
+
+### 为错误创建注释
+
+请参阅[为错误创建注释](https://docs.github.com/zh/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error)。
+
+Gitea Actions目前不支持此功能。
+
+### 表达式
+
+对于 [表达式](https://docs.github.com/en/actions/learn-github-actions/expressions), 当前仅 [`always()`](https://docs.github.com/en/actions/learn-github-actions/expressions#always) 被支持。
+
+## 缺失的UI功能
+
+### 预处理和后处理步骤
+
+预处理和后处理步骤在Job日志用户界面中没有自己的用户界面。
+
+### 服务步骤
+
+服务步骤在Job日志用户界面中没有自己的用户界面。
+
+## 不一样的行为
+
+### 下载Actions
+
+当 `[actions].DEFAULT_ACTIONS_URL` 保持默认值为 `github` 时，Gitea将会从 https://github.com 下载相对路径的actions。比如：
+如果你使用 `uses: actions/checkout@v4`，Gitea将会从 https://github.com/actions/checkout.git 下载这个 actions 项目。
+如果你想要从另外一个 Git服务下载actions，你只需要使用绝对URL `uses: https://gitea.com/actions/checkout@v4` 来下载。
+
+如果你的 Gitea 实例是部署在一个互联网限制的网络中，也可以使用绝对地址来下载 actions。你也可以将配置项修改为 `[actions].DEFAULT_ACTIONS_URL = self`。这样所有的相对路径的actions引用，将不再会从 github.com 去下载，而会从这个 Gitea 实例自己的仓库中去下载。例如： `uses: actions/checkout@v4` 将会从 `[server].ROOT_URL`/actions/checkout.git 这个地址去下载 actions。
+
+设置`[actions].DEFAULT_ACTIONS_URL`进行配置。请参阅[配置备忘单](../../administration/config-cheat-sheet.md#actions-actions)。
+
+### 上下文可用性
+
+不检查上下文可用性，因此您可以在更多地方使用env上下文。
+请参阅[上下文可用性](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability)。
diff --git a/docs/document/usage/actions/design.md b/docs/document/usage/actions/design.md
new file mode 100644
index 0000000..deb422a
--- /dev/null
+++ b/docs/document/usage/actions/design.md
@@ -0,0 +1,124 @@
+---
+date: "2023-05-24T15:00:00+08:00"
+slug: "design"
+sidebar_position: 40
+---
+
+# Gitea Actions设计
+
+Gitea Actions由多个组件组成。本文档将对它们进行逐个描述。
+
+## Act
+
+[nektos/act](https://github.com/nektos/act) 项目是一个优秀的工具，允许你在本地运行GitHub Actions。
+我们受到了它的启发，并思考它是否可能为Gitea运行Actions。
+
+然而，尽管[nektos/act](https://github.com/nektos/act)被设计为一个命令行工具，但我们实际上需要的是一个专为Gitea修改的Go库。
+因此，我们在[gitea/act](https://gitea.com/gitea/act)基础上进行了分叉。
+
+这是一个软分叉，将定期跟进上游。
+虽然添加了一些自定义提交，但我们会尽力避免对原始代码进行太多更改。
+
+分叉的 act 只是Gitea特定用途的桥接或适配器。
+还添加了一些额外的提交，例如：
+
+- 将执行日志输出到日志记录器钩子，以便报告给Gitea
+- 禁用 GraphQL URL，因为Gitea不支持它
+- 每个Job启动一个新的容器，而不是重复使用，以确保隔离性。
+
+这些修改没有理由合并到上游。
+如果用户只想在本地运行可信的Actions，它们是没有意义的。
+
+然而，将来可能会出现重叠，例如两个项目都需要的必要错误修复或新功能。
+在这些情况下，我们将向上游仓库贡献变更。
+
+## act runner
+
+Gitea的Runner被称为act runner，因为它基于act。
+
+与其他CIRunner一样，我们将其设计为Gitea的外部部分，这意味着它应该在与Gitea不同的服务器上运行。
+
+为了确保Runner连接到正确的Gitea实例，我们需要使用令牌注册它。
+此外，Runner通过声明自己的标签向Gitea报告它可以运行的Job类型。
+
+之前，我们提到工作流文件中的 `runs-on: ubuntu-latest` 表示该Job将在具有`ubuntu-latest`标签的Runner上运行。
+但是，Runner如何知道要运行 `ubuntu-latest`？答案在于将标签映射到环境。
+这就是为什么在注册过程中添加自定义标签时，需要输入一些复杂内容，比如`my_custom_label:docker://centos:7`。
+这意味着Runner可以接受需要在`my_custom_label`上运行的Job，并通过使用`centos:7`镜像的Docker容器来运行它。
+
+然而，Docker不是唯一的选择。
+act 也支持直接在主机上运行Job。
+这是通过像`linux_arm:host`这样的标签实现的。
+这个标签表示Runner可以接受需要在`linux_arm`上运行的Job，并直接在主机上运行它们。
+
+标签的设计遵循格式`label[:schema[:args]]`。
+如果省略了schema，则默认为`host`。
+
+因此，
+
+- `my_custom_label:docker://node:18`：使用`node:18 Docker`镜像运行带有`my_custom_label`标签的Job。
+- `my_custom_label:host`：在主机上直接运行带有`my_custom_label`标签的Job。
+- `my_custom_label`：等同于`my_custom_label:host`。
+- `my_custom_label:vm:ubuntu-latest`：（仅为示例，未实现）使用带有`ubuntu-latest` ISO的虚拟机运行带有`my_custom_label`标签的Job。
+
+## 通信协议
+
+由于act runner是Gitea的独立部分，我们需要一种协议让Runner与Gitea实例进行通信。
+然而，我们不认为让Gitea监听一个新端口是个好主意。
+相反，我们希望重用HTTP端口，这意味着我们需要一个与HTTP兼容的协议。
+因此，我们选择使用基于HTTP的gRPC。
+
+我们使用[actions-proto-def](https://gitea.com/gitea/actions-proto-def) 和 [actions-proto-go](https://gitea.com/gitea/actions-proto-go) 进行连接。
+有关 gRPC 的更多信息，请访问[其官方网站](https://grpc.io/)。
+
+## 网络架构
+
+让我们来看一下整体的网络架构。
+这将帮助您解决一些问题，并解释为什么使用回环地址注册Runner是个不好的主意。
+
+![network](../../../static/images/usage/actions/network.png)
+
+图片中标记了四个网络连接，并且箭头的方向表示建立连接的方向。
+
+### 连接 1，act runner到Gitea实例
+
+act runner 必须能够连接到Gitea以接收任务并发送执行结果回来。
+
+### 连接 2，Job容器到Gitea实例
+
+即使Job容器位于同一台机器上，它们的网络命名空间与Runner不同。
+举个例子，如果工作流中包含 `actions/checkout@v4`，Job容器需要连接到Gitea来获取代码。
+获取代码并不总是运行某些Job所必需的，但在大多数情况下是必需的。
+
+如果您使用回环地址注册Runner，当Runner与Gitea在同一台机器上时，Runner可以连接到Gitea。
+然而，如果Job容器尝试从本地主机获取代码，它将失败，因为Gitea不在同一个容器中。
+
+### 连接 3，act runner到互联网
+
+当您使用诸如 `actions/checkout@v4` 的一些Actions时，act runner下载的是脚本，而不是Job容器。
+默认情况下，它从[github.com](http://github.com/)下载，因此需要访问互联网。如果您设置的是 self，
+那么默认将从您的当前Gitea实例下载，那么此步骤不需要连接到互联网。
+它还默认从Docker Hub下载一些Docker镜像，这也需要互联网访问。
+
+然而，互联网访问并不是绝对必需的。
+您可以配置您的Gitea实例从您的内部网络设施中获取 Actions 或镜像。
+
+实际上，您的Gitea实例可以同时充当 Actions 市场和镜像注册表。
+您可以将GitHub上的Actions仓库镜像到您的Gitea实例，并将其用作普通Actions。
+而 [Gitea 容器注册表](usage/packages/container.md) 可用作Docker镜像注册表。
+
+### 连接 4，Job容器到互联网
+
+当使用诸如`actions/setup-go@v5`的Actions时，可能需要从互联网下载资源，以设置Job容器中的Go语言环境。
+因此，成功完成这些Actions需要访问互联网。
+
+然而，这也是可选的。
+您可以使用自定义的Actions来避免依赖互联网访问，或者可以使用已安装所有依赖项的打包的Docker镜像来运行Job。
+
+## 总结
+
+使用Gitea Actions只需要确保Runner能够连接到Gitea实例。
+互联网访问是可选的，但如果没有互联网访问，将需要额外的工作。
+换句话说：当Runner能够自行查询互联网时，它的工作效果最好，但您不需要将其暴露给互联网（无论是单向还是双向）。
+
+如果您在使用Gitea Actions时遇到任何网络问题，希望上面的图片能够帮助您进行故障排除。
diff --git a/docs/document/usage/actions/faq.md b/docs/document/usage/actions/faq.md
new file mode 100644
index 0000000..f18116f
--- /dev/null
+++ b/docs/document/usage/actions/faq.md
@@ -0,0 +1,167 @@
+---
+date: "2023-05-24T15:00:00+08:00"
+slug: "faq"
+sidebar_position: 100
+---
+
+# Gitea Actions常见问题解答
+
+本页面包含一些关于Gitea Actions的常见问题和答案。
+
+## 是否可以在我的实例中默认禁用新仓库的Actions？
+
+是的，当您为实例启用Actions时，您可以选择默认启用actions单元以适用于所有新仓库。
+
+```ini
+[repository]
+; 去掉 repo.actions 将不会为新仓库自动启用actions
+DEFAULT_REPO_UNITS = ...,repo.actions
+```
+
+## 在工作流文件中应该使用`github.xyz`还是`gitea.xyz`？
+
+您可以使用`github.xyz`，Gitea将正常工作。
+如前所述，Gitea Actions的设计是与GitHub Actions兼容的。
+然而，我们建议在工作流文件中使用`gitea.xyz`，以防止在工作流文件中出现不同类型的密钥（因为您在Gitea上使用此工作流，而不是GitHub）。
+不过，这完全是可选的，因为目前这两个选项的效果是相同的。
+
+## 使用`actions/checkout@v4`等Actions时，Job容器会从何处下载脚本？
+
+GitHub 上有成千上万个 [Actions 脚本](https://github.com/marketplace?type=actions)。
+当您编写 `uses: actions/checkout@v4` 时，它默认会从 [github.com/actions/checkout](https://github.com/actions/checkout) 下载脚本。
+那如果您想使用一些托管在其它平台上的脚本呢，比如在 gitea.com 上的？
+
+好消息是，您可以指定要从任何位置使用Actions的URL前缀。
+这是Gitea Actions中的额外语法。
+例如：
+
+- `uses: https://gitea.com/xxx/xxx@xxx`
+- `uses: https://github.com/xxx/xxx@xxx`
+- `uses: http://your_gitea_instance.com/xxx@xxx`
+
+注意，`https://`或`http://`前缀是必需的！
+
+这是与 GitHub Actions 的一个区别，GitHub Actions 只允许使用托管在 GitHub 上的 actions 脚本。
+但用户理应拥有权利去灵活决定如何运行 Actions。
+
+另外，如果您希望您的 Runner 默认从您自己的 Gitea 实例下载 Actions，可以通过设置 `[actions].DEFAULT_ACTIONS_URL`进行配置。
+参见[配置速查表](../../administration/config-cheat-sheet.md#actions-actions)。
+
+## 如何限制Runner的权限？
+
+Runner仅具有连接到您的Gitea实例的权限。
+当任何Runner接收到要运行的Job时，它将临时获得与Job关联的仓库的有限权限。
+如果您想为Runner提供更多权限，允许它访问更多私有仓库或外部系统，您可以向其传递[密钥](usage/actions/secrets.md)。
+
+对于 Actions 的细粒度权限控制是一项复杂的工作。
+在未来，我们将添加更多选项以使Gitea更可配置，例如允许对仓库进行更多写访问或对同一组织中的所有仓库进行读访问。
+
+## 如何避免被黑客攻击？
+
+有两种可能的攻击类型：未知的Runner窃取您的仓库中的代码或密钥，或恶意脚本控制您的Runner。
+
+避免前者意味着不允许您不认识的人为您的仓库、组织或实例注册Runner。
+
+后者要复杂一些。
+如果您为公司使用私有的Gitea实例，您可能不需要担心安全问题，因为您信任您的同事，并且可以追究他们的责任。
+
+对于公共实例，情况略有不同。
+以下是我们在 [gitea.com](http://gitea.com/)上的做法：
+
+- 我们仅为 "gitea" 组织注册Runner，因此我们的Runner不会执行来自其他仓库的Job。
+- 我们的Runner始终在隔离容器中运行Job。虽然可以直接在主机上进行这样的操作，但出于安全考虑，我们选择不这样做。
+- 对于 fork 的拉取请求，需要获得批准才能运行Actions。参见[#22803](https://github.com/go-gitea/gitea/pull/22803)。
+- 如果有人在[gitea.com](http://gitea.com/)为其仓库或组织注册自己的Runner，我们不会反对，只是不会在我们的组织中使用它。然而，他们应该注意确保该Runner不被他们不认识的其他用户使用。
+
+## act runner支持哪些操作系统？
+
+它在Linux、macOS和Windows上运行良好。
+虽然理论上支持其他操作系统，但需要进一步测试。
+
+需要注意的一点是，如果选择直接在主机上运行Job而不是在Job容器中运行，操作系统之间的环境差异可能会导致意外的失败。
+
+例如，在大多数情况下，Windows上没有可用的bash，而act尝试默认使用bash运行脚本。
+因此，您需要在工作流文件中将默认shell指定为`powershell`，参考[defaults.run](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrun)。
+
+```yaml
+defaults:
+  run:
+    shell: powershell
+```
+
+## 为什么选择GitHub Actions？为什么不选择与GitLab CI/CD兼容的工具？
+
+[@lunny](https://gitea.com/lunny)在实现Actions的[问题](https://github.com/go-gitea/gitea/issues/13539)中已经解释过这个问题。
+此外，Actions不仅是一个CI/CD 系统，还是一个自动化工具。
+
+在开源世界中，已经有许多[市场上的Actions](https://github.com/marketplace?type=actions)实现了。
+能够重用它们是令人兴奋的。
+
+## 如果它在多个标签上运行，例如 `runs-on: [label_a, label_b]`，会发生什么？
+
+这是有效的语法。
+它意味着它应该在具有`label_a` **和** `label_b`标签的Runner上运行，参考[GitHub Actions的工作流语法](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)。
+不幸的是，act runner 并不支持这种方式。
+如上所述，我们将标签映射到环境：
+
+- `ubuntu` → `ubuntu:22.04`
+- `centos` → `centos:8`
+
+但我们需要将标签组映射到环境，例如：
+
+- `[ubuntu]` → `ubuntu:22.04`
+- `[with-gpu]` → `linux:with-gpu`
+- `[ubuntu, with-gpu]` → `ubuntu:22.04_with-gpu`
+
+我们还需要重新设计任务分配给Runner的方式。
+具有`ubuntu`、`centos`或`with-gpu`的Runner并不一定表示它可以接受`[centos, with-gpu]`的Job。
+因此，Runner应该通知Gitea实例它只能接受具有 `[ubuntu]`、`[centos]`、`[with-gpu]` 和 `[ubuntu, with-gpu]`的Job。
+这不是一个技术问题，只是在早期设计中被忽视了。
+参见[runtime.go#L65](https://gitea.com/gitea/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65)。
+
+目前，act runner尝试匹配标签中的每一个，并使用找到的第一个匹配项。
+
+## 代理标签和自定义标签对于Runner有什么区别？
+
+![labels](../../../static/images/usage/actions/labels.png)
+
+代理标签是由Runner在注册过程中向Gitea实例报告的。
+而自定义标签则是由Gitea的管理员或组织或仓库的所有者手动添加的（取决于Runner所属的级别）。
+
+然而，目前这方面的设计还有待改进，因为它目前存在一些不完善之处。
+您可以向已注册的Runner添加自定义标签，比如 `centos`，这意味着该Runner将接收具有`runs-on: centos`的Job。
+然而，Runner可能不知道要使用哪个环境来执行该标签，导致它使用默认镜像或导致逻辑死胡同。
+这个默认值可能与用户的期望不符。
+参见[runtime.go#L71](https://gitea.com/gitea/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71)。
+
+与此同时，如果您想更改Runner的标签，我们建议您重新注册Runner。
+
+## Gitea Actions runner会有更多的实现吗？
+
+虽然我们希望提供更多的选择，但由于我们有限的人力资源，act runner将是唯一受支持的官方Runner。
+然而，无论您如何决定，Gitea 和act runner都是完全开源的，所以任何人都可以创建一个新的/更好的实现。
+我们支持您的选择，无论您如何决定。
+如果您选择分支act runner来创建自己的版本，请在您认为您的更改对其他人也有帮助的情况下贡献这些更改。
+
+## Gitea 支持哪些工作流触发事件？
+
+表格中列出的所有事件都是支持的，并且与 GitHub 兼容。
+对于仅 GitHub 支持的事件，请参阅 GitHub 的[文档](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows)。
+
+| 触发事件                    | 活动类型                                                                                                                 |
+|-----------------------------|--------------------------------------------------------------------------------------------------------------------------|
+| create                      | 不适用                                                                                                                   |
+| delete                      | 不适用                                                                                                                   |
+| fork                        | 不适用                                                                                                                   |
+| gollum                      | 不适用                                                                                                                   |
+| push                        | 不适用                                                                                                                   |
+| issues                      | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `milestoned`, `demilestoned`, `labeled`, `unlabeled` |
+| issue_comment               | `created`, `edited`, `deleted`                                                                                           |
+| pull_request                | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `synchronize`, `labeled`, `unlabeled`                |
+| pull_request_review         | `submitted`, `edited`                                                                                                    |
+| pull_request_review_comment | `created`, `edited`                                                                                                      |
+| release                     | `published`, `edited`                                                                                                    |
+| registry_package            | `published`                                                                                                              |
+
+> 对于 `pull_request` 事件，在 [GitHub Actions](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request) 中 `ref` 是 `refs/pull/:prNumber/merge`，它指向这个拉取请求合并提交的一个预览。但是 Gitea 没有这种 reference。
+> 因此，Gitea Actions 中 `ref` 是 `refs/pull/:prNumber/head`，它指向这个拉取请求的头分支而不是合并提交的预览。
diff --git a/docs/document/usage/actions/overview.md b/docs/document/usage/actions/overview.md
new file mode 100644
index 0000000..c364984
--- /dev/null
+++ b/docs/document/usage/actions/overview.md
@@ -0,0 +1,42 @@
+---
+date: "2023-05-24T15:00:00+08:00"
+slug: "overview"
+sidebar_position: 1
+---
+
+# Overview
+
+从Gitea **1.19**版本开始，Gitea Actions成为了内置的CI/CD解决方案。
+
+## 名称
+
+Gitea Actions与[GitHub Actions](https://github.com/features/actions)相似且兼容，它的名称也受到了它的启发。
+为了避免混淆，在这里我们明确了拼写方式：
+
+- "Gitea Actions"（两个单词都大写且带有"s"）是Gitea功能的名称。
+- "GitHub Actions"是GitHub功能的名称。
+- "Actions"根据上下文的不同可以指代以上任意一个。在本文档中指代的是"Gitea Actions"。
+- "action"或"actions"指代一些要使用的脚本/插件，比如"actions/checkout@v4"或"actions/cache@v3"。
+
+## Runner
+
+和其他CI/CD解决方案一样，Gitea不会自己运行Job，而是将Job委托给Runner。
+Gitea Actions的Runner被称为[act runner](https://gitea.com/gitea/act_runner)，它是一个独立的程序，也是用Go语言编写的。
+它是基于[nektos/act](http://github.com/nektos/act)的一个[分支](https://gitea.com/gitea/act) 。
+
+由于Runner是独立部署的，可能存在潜在的安全问题。
+为了避免这些问题，请遵循两个简单的规则：
+
+- 不要为你的仓库、组织或实例使用你不信任的Runner。
+- 不要为你不信任的仓库、组织或实例提供Runner。
+
+对于内部使用的Gitea实例，比如企业或个人使用的实例，这两个规则不是问题，它们自然而然就是如此。
+然而，对于公共的Gitea实例，比如[gitea.com](https://gitea.com)，在添加或使用Runner时应当牢记这两个规则。
+
+## 状态
+
+Gitea Actions仍然在开发中，因此可能存在一些错误和缺失的功能。
+并且在稳定版本（v1.20或更高版本）之前可能会进行一些重大的更改。
+
+如果情况发生变化，我们将在此处进行更新。
+因此，请在其他地方找到过时文章时参考此处的内容。
diff --git a/docs/document/usage/actions/quickstart.md b/docs/document/usage/actions/quickstart.md
new file mode 100644
index 0000000..7373e8e
--- /dev/null
+++ b/docs/document/usage/actions/quickstart.md
@@ -0,0 +1,131 @@
+---
+date: "2023-05-24T15:00:00+08:00"
+slug: "quickstart"
+sidebar_position: 10
+---
+
+# 快速入门
+
+本页面将指导您使用Gitea Actions的过程。
+
+## 设置Gitea
+
+首先，您需要一个Gitea实例。
+您可以按照[文档](installation/from-package.md) 来设置一个新实例或升级现有实例。
+无论您如何安装或运行Gitea，只要版本号是1.19.0或更高即可。
+
+从1.21.0开始，默认情况下，Actions是启用的。如果您正在使用1.21.0之前的版本，您需要将以下内容添加到配置文件中以启用它：
+
+```ini
+[actions]
+ENABLED=true
+```
+
+如果您想了解更多信息或在配置过程中遇到任何问题，请参考[配置速查表](../../administration/config-cheat-sheet.md#actions-actions)。
+
+### 设置Runner
+
+Gitea Actions需要[act runner](https://gitea.com/gitea/act_runner) 来运行Job。
+为了避免消耗过多资源并影响Gitea实例，建议您在与Gitea实例分开的机器上启动Runner。
+
+您可以使用[预构建的二进制文件](http://dl.gitea.com/act_runner)或[容器镜像](https://hub.docker.com/r/gitea/act_runner/tags)来设置Runner。
+
+在进一步操作之前，建议您先使用预构建的二进制文件以命令行方式运行它，以确保它与您的环境兼容，尤其是如果您在本地主机上运行Runner。
+如果出现问题，这样调试起来会更容易。
+
+该Runner可以在隔离的Docker容器中运行Job，因此您需要确保已安装Docker并且Docker守护进程正在运行。
+虽然这不是严格必需的，因为Runner也可以直接在主机上运行Job，这取决于您的配置方式。
+然而，建议使用Docker运行Job，因为它更安全且更易于管理。
+
+在运行Runner之前，您需要使用以下命令将其注册到Gitea实例中：
+
+```bash
+./act_runner register --no-interactive --instance <instance> --token <token>
+```
+
+需要两个必需的参数：`instance` 和 `token`。
+
+`instance`是您的Gitea实例的地址，如`http://192.168.8.8:3000`或`https://gitea.com`。
+Runner和Job容器（由Runner启动以执行Job）将连接到此地址。
+这意味着它可能与用于Web访问的`ROOT_URL`不同。
+使用回环地址（例如 `127.0.0.1` 或 `localhost`）是一个不好的选择。
+如果不确定使用哪个地址，通常选择局域网地址即可。
+
+`token` 用于身份验证和标识，例如 `P2U1U0oB4XaRCi8azcngmPCLbRpUGapalhmddh23`。
+它只能使用一次，并且不能用于注册多个Runner。
+您可以从以下位置获取不同级别的`token`,从而创建出相应级别的`runner`
+
+- 实例级别：管理员设置页面，例如 `<your_gitea.com>/admin/actions/runners`。
+- 组织级别：组织设置页面，例如 `<your_gitea.com>/<org>/settings/actions/runners`。
+- 存储库级别：存储库设置页面，例如 `<your_gitea.com>/<owner>/<repo>/settings/actions/runners`。
+
+![register runner](../../../static/images/usage/actions/register-runner.png)
+
+注册后，当前目录中将出现一个名为 `.runner` 的新文件，该文件存储了注册信息。
+请不要手动编辑该文件。
+如果该文件丢失或损坏，只需删除它然后重新注册即可。
+
+最后，是时候启动Runner了：
+
+```bash
+./act_runner daemon
+```
+
+您可以在管理页面上看到新的Runner：
+
+![view runner](../../../static/images/usage/actions/view-runner.png)
+
+您可以通过访问[act runner](usage/actions/act-runner.md) 获取更多信息。
+
+### 使用Actions
+
+即使对于启用了Gitea实例的Actions，存储库仍默认禁用Actions。
+
+要启用它，请转到存储库的设置页面，例如`your_gitea.com/<owner>/repo/settings`，然后启用`Enable Repository Actions`。
+
+![enable actions](../../../static/images/usage/actions/enable-actions.png)
+
+接下来的步骤可能相当复杂。
+您需要学习Actions的[工作流语法](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)，并编写您想要的工作流文件。
+
+不过，我们可以从一个简单的演示开始：
+
+```yaml
+name: Gitea Actions Demo
+run-name: ${{ gitea.actor }} is testing out Gitea Actions 🚀
+on: [push]
+
+jobs:
+  Explore-Gitea-Actions:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "🎉 The job was automatically triggered by a ${{ gitea.event_name }} event."
+      - run: echo "🐧 This job is now running on a ${{ runner.os }} server hosted by Gitea!"
+      - run: echo "🔎 The name of your branch is ${{ gitea.ref }} and your repository is ${{ gitea.repository }}."
+      - name: Check out repository code
+        uses: actions/checkout@v4
+      - run: echo "💡 The ${{ gitea.repository }} repository has been cloned to the runner."
+      - run: echo "🖥️ The workflow is now ready to test your code on the runner."
+      - name: List files in the repository
+        run: |
+          ls ${{ gitea.workspace }}
+      - run: echo "🍏 This job's status is ${{ job.status }}."
+```
+
+您可以将上述示例上传为一个以`.yaml`扩展名的文件，放在存储库的`.gitea/workflows/`目录中，例如`.gitea/workflows/demo.yaml`。
+您可能会注意到，这与[GitHub Actions的快速入门](https://docs.github.com/en/actions/quickstart)非常相似。
+这是因为Gitea Actions在尽可能兼容GitHub Actions的基础上进行设计。
+
+请注意，演示文件中包含一些表情符号。
+请确保您的数据库支持它们，特别是在使用MySQL时。
+如果字符集不是`utf8mb4`，将出现错误，例如`Error 1366 (HY000): Incorrect string value: '\\xF0\\x9F\\x8E\\x89 T...' for column 'name' at row 1`。
+有关更多信息，请参阅[数据库准备工作](../../installation/database-preparation.md#mysqlmariadb)。
+
+或者，您可以从演示文件中删除所有表情符号，然后再尝试一次。
+
+`on: [push]` 这一行表示当您向该存储库推送提交时，工作流将被触发。
+然而，当您上传 YAML 文件时，它也会推送一个提交，所以您应该在"Actions"标签中看到一个新的任务。
+
+![view job](../../../static/images/usage/actions/view-job.png)
+
+做得好！您已成功开始使用Actions。
diff --git a/docs/document/usage/actions/secrets.md b/docs/document/usage/actions/secrets.md
new file mode 100644
index 0000000..b87c281
--- /dev/null
+++ b/docs/document/usage/actions/secrets.md
@@ -0,0 +1,28 @@
+---
+date: "2023-05-23T09:00:00+08:00"
+slug: "secrets"
+sidebar_position: 50
+---
+
+# 密钥管理
+
+密钥管理允许您在用户、组织或仓库中存储敏感信息。
+密钥管理在 Gitea 1.19+ 版本中可用。
+
+## 设置密钥名称
+
+以下规则适用于密钥名称：
+
+- 密钥名称只能包含字母数字字符 (`[a-z]`, `[A-Z]`, `[0-9]`) 或下划线 (`_`)。不允许使用空格。
+
+- 密钥名称不能以 `GITHUB_` 和 `GITEA_` 前缀开头。
+
+- 密钥名称不能以数字开头。
+
+- 密钥名称不区分大小写。
+
+- 密钥名称在创建它们的级别上必须是唯一的。
+
+例如，对于在仓库级别创建的密钥，它在该仓库中必须具有唯一的名称；对于在组织级别创建的密钥，它在该级别上必须具有唯一的名称。
+
+如果在多个级别上存在具有相同名称的密钥，则最低级别的密钥优先生效。例如，如果组织级别的密钥与仓库级别的密钥具有相同的名称，则仓库级别的密钥将优先生效。
diff --git a/docs/document/usage/actions/variables.md b/docs/document/usage/actions/variables.md
new file mode 100644
index 0000000..b84cdf9
--- /dev/null
+++ b/docs/document/usage/actions/variables.md
@@ -0,0 +1,34 @@
+---
+date: "2024-04-10T22:21:00+08:00"
+slug: "actions-variables"
+sidebar_position: 25
+---
+
+# 变量
+
+您可以创建用户、组织和仓库级别的变量。变量的级别取决于创建它的位置。当创建变量时，变量的名称会被
+转换为大写，在yaml文件中引用时需要使用大写。
+
+## 命名规则
+
+以下规则适用于变量名：
+
+- 变量名称只能包含字母数字字符 (`[a-z]`, `[A-Z]`, `[0-9]`) 或下划线 (`_`)。不允许使用空格。
+- 变量名称不能以 `GITHUB_` 和 `GITEA_` 前缀开头。
+- 变量名称不能以数字开头。
+- 变量名称不区分大小写。
+- 变量名称在创建它们的级别上必须是唯一的。
+- 变量名称不能为 `CI`。
+
+## 使用
+
+创建配置变量后，它们将自动填充到 `vars` 上下文中。您可以在工作流中使用类似 
+```yaml
+${{ vars.VARIABLE_NAME }}
+```
+ 这样的表达式来使用它们。
+
+## 优先级
+
+如果同名变量存在于多个级别，则级别最低的变量优先。
+仓库级别的变量总是比组织或者用户级别的变量优先被选中。
diff --git a/docs/document/usage/agit-support.md b/docs/document/usage/agit-support.md
new file mode 100644
index 0000000..31d6bb8
--- /dev/null
+++ b/docs/document/usage/agit-support.md
@@ -0,0 +1,45 @@
+---
+date: "2023-05-23T09:00:00+08:00"
+slug: "agit"
+sidebar_position: 12
+aliases:
+  - /zh-cn/agit-setup
+---
+
+# AGit
+
+在 Gitea `1.13` 版本中，添加了对 [AGit](https://git-repo.info/zh/2020/03/agit-flow-and-git-repo/) 的支持。AGit 允许用户在没有仓库写入权限的情况下直接创建拉取请求，也不需要分叉仓库。这有助于减少重复仓库的数量，降低不必要的磁盘使用量。
+
+:::note
+服务器端需要 Git 版本 2.29 或更高版本才能正常运行。
+:::
+
+## 使用 AGit 创建 PR
+
+AGit 允许在推送代码到远程仓库时创建 PR（合并请求）。
+通过在推送时使用特定的 refspec（git 中已知的位置标识符），可以实现这一功能。
+下面的示例说明了这一点：
+
+```shell
+git push origin HEAD:refs/for/main
+```
+
+该命令的结构如下：
+
+- `HEAD`：目标分支
+- `refs/<for|draft|for-review>/<branch>`：目标 PR 类型
+  - `for`：创建一个以 `<branch>` 为目标分支的普通 PR
+  - `draft`/`for-review`：目前被静默忽略
+- `<branch>/<session>`：要打开 PR 的目标分支
+- `-o <topic|title|description>`：PR 的选项
+  - `title`：PR 的标题
+  - `topic`：PR 应该打开的分支名称
+  - `description`：PR 的描述
+  - `force-push=true`: 是否强制更新目标分支
+    - 注意: 如果不传值，只用 `-o force-push` 也同样可以正常工作。
+
+下面是另一个高级示例，用于创建一个以 `topic`、`title` 和 `description` 为参数的新 PR，目标分支是 `main`：
+
+```shell
+git push origin HEAD:refs/for/main -o topic="Topic of my PR" -o title="Title of the PR" -o description="# The PR Description\nThis can be **any** markdown content.\n- [x] Ok"
+```
diff --git a/docs/document/usage/agit.md b/docs/document/usage/agit.md
new file mode 100644
index 0000000..e0716a4
--- /dev/null
+++ b/docs/document/usage/agit.md
@@ -0,0 +1,48 @@
+---
+date: "	2022-09-01T20:50:42+0000"
+slug: "agit"
+sidebar_position: 12
+aliases:
+  - /en-us/agit-setup
+  - /agit-setup
+---
+
+# AGit
+
+In Gitea `1.13`, support for [AGit](https://git-repo.info/en/2020/03/agit-flow-and-git-repo/) was added. AGit enables users to create pull requests directly, even without write permissions of the repository, eliminating the need to fork it. This helps reduce the number of duplicated repositories and minimizes unnecessary disk usage.
+
+:::note
+Git version 2.29 or higher is required on the server side for this to work.
+:::
+
+## Creating PRs with AGit
+
+AGit allows to create PRs while pushing code to the remote repo.
+This can be done by pushing to the branch followed by a specific refspec (a location identifier known to git).
+The following example illustrates this:
+
+```shell
+git push origin HEAD:refs/for/main
+```
+
+The command has the following structure:
+
+- `HEAD`: The target branch
+- `origin`: The target repository (not a fork!)
+- `HEAD`: The local branch containing the changes you are proposing
+- `refs/<for|draft|for-review>/<branch>`: The target PR type and configuration
+  - `for`: Create a normal PR with `<branch>` as the target branch
+  - `draft`/`for-review`: Currently ignored silently
+  - `<branch>/`: The branch you want your changes to be merged into
+- `-o <topic|title|description>`: Options for the PR
+  - `topic`: The topic of this change. It will become the name of the branch holding the changes waiting for review.  This is REQUIRED to trigger a pull request.
+  - `title`: The PR title (optional but recommended), only used for topics not already having an associated PR.
+  - `description`: The PR description (optional but recommended), only used for topics not already having an associated PR.
+  - `force-push=true`: Specifies whether to force-update the target branch.
+    - Note: omitting the value and using just `-o force-push` will also work.
+
+Here's another advanced example for creating a new PR targeting `main` with `topic`, `title`, and `description`:
+
+```shell
+git push origin HEAD:refs/for/main -o topic="topic_of_my_PR" -o title="Title of the PR" -o description="# The PR Description\nThis can be **any** markdown content.\n- [x] Ok"
+```
diff --git a/docs/document/usage/blame.md b/docs/document/usage/blame.md
new file mode 100644
index 0000000..5fa0dc5
--- /dev/null
+++ b/docs/document/usage/blame.md
@@ -0,0 +1,29 @@
+---
+date: "2023-08-14T00:00:00+00:00"
+slug: "blame"
+sidebar_position: 13
+aliases:
+  - /en-us/blame
+---
+
+# Blame File View
+
+Gitea supports viewing the line-by-line revision history for a file also known as blame view.
+You can also use [`git blame`](https://git-scm.com/docs/git-blame) on the command line to view the revision history of lines within a file.
+
+1. Navigate to and open the file whose line history you want to view.
+1. Click the `Blame` button in the file header bar.
+1. The new view shows the line-by-line revision history for a file with author and commit information on the left side.
+1. To navigate to an older commit, click the ![versions](../../static//octicon-versions.svg) icon.
+
+## Ignore commits in the blame view
+
+All revisions specified in the `.git-blame-ignore-revs` file are hidden from the blame view.
+This is especially useful to hide reformatting changes and keep the benefits of `git blame`.
+Lines that were changed or added by an ignored commit will be blamed on the previous commit that changed that line or nearby lines.
+The `.git-blame-ignore-revs` file must be located in the root directory of the repository.
+For more information like the file format, see [the `git blame --ignore-revs-file` documentation](https://git-scm.com/docs/git-blame#Documentation/git-blame.txt---ignore-revs-fileltfilegt).
+
+### Bypassing `.git-blame-ignore-revs` in the blame view
+
+If the blame view for a file shows a message about ignored revisions, you can see the normal blame view by appending the url parameter `?bypass-blame-ignore=true`.
diff --git a/docs/document/usage/blocking-users.md b/docs/document/usage/blocking-users.md
new file mode 100644
index 0000000..639421b
--- /dev/null
+++ b/docs/document/usage/blocking-users.md
@@ -0,0 +1,47 @@
+---
+date: "2024-01-31T00:00:00+00:00"
+slug: "blocking-user"
+sidebar_position: 25
+aliases:
+  - /en-us/webhooks
+---
+
+# Blocking a user
+
+Gitea supports blocking of users to restrict how they can interact with you and your content.
+
+You can block a user in your account settings, from the user's profile or from comments created by the user.
+The user is not directly notified about the block, but they can notice they are blocked when they attempt to interact with you.
+Organization owners can block anyone who is not a member of the organization too.
+If a blocked user has admin permissions, they can still perform all actions even if blocked.
+
+### When you block a user
+
+- the user stops following you
+- you stop following the user
+- the user's stars are removed from your repositories
+- your stars are removed from their repositories
+- the user stops watching your repositories
+- you stop watching their repositories
+- the user's issue assignments are removed from your repositories
+- your issue assignments are removed from their repositories
+- the user is removed as a collaborator on your repositories
+- you are removed as a collaborator on their repositories
+- any pending repository transfers to or from the blocked user are canceled
+
+### When you block a user, the user cannot
+
+- follow you
+- watch your repositories
+- star your repositories
+- fork your repositories
+- transfer repositories to you
+- open issues or pull requests on your repositories
+- comment on issues or pull requests you've created
+- comment on issues or pull requests on your repositories
+- react to your comments on issues or pull requests
+- react to comments on issues or pull requests on your repositories
+- assign you to issues or pull requests
+- add you as a collaborator on their repositories
+- send you notifications by @mentioning your username
+- be added as team member (if blocked by an organization)
diff --git a/docs/document/usage/clone-filter.md b/docs/document/usage/clone-filter.md
new file mode 100644
index 0000000..90b6709
--- /dev/null
+++ b/docs/document/usage/clone-filter.md
@@ -0,0 +1,18 @@
+---
+date: "2023-05-23T09:00:00+08:00"
+
+slug: "clone-filters"
+sidebar_position: 25
+aliases:
+  - /zh-cn/clone-filters
+---
+
+# 克隆过滤器 (部分克隆)
+
+Git 引入了 `--filter` 选项用于 `git clone` 命令，该选项可以过滤掉大文件和对象（如 blob），从而创建一个仓库的部分克隆。克隆过滤器对于大型仓库和/或按流量计费的连接特别有用，因为完全克隆（不使用 `--filter`）可能会很昂贵（需要下载所有历史数据）。
+
+这需要 Git 2.22 或更高版本，无论是在 Gitea 服务器上还是在客户端上都需要如此。为了使克隆过滤器正常工作，请确保客户端上的 Git 版本至少与服务器上的版本相同（或更高）。以管理员身份登录到 Gitea，然后转到管理后台 -> 应用配置，查看服务器的 Git 版本。
+
+默认情况下，克隆过滤器是启用的，除非在 `[git]` 下将 `DISABLE_PARTIAL_CLONE` 设置为 `true`。
+
+请参阅 [GitHub 博客文章：了解部分克隆](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/) 以获取克隆过滤器的常见用法（无 Blob 和无树的克隆），以及 [GitLab 部分克隆文档](https://docs.gitlab.com/ee/topics/git/partial_clone.html) 以获取更高级的用法（例如按文件大小过滤和取消过滤以将部分克隆转换为完全克隆）。
diff --git a/docs/document/usage/code-owners.md b/docs/document/usage/code-owners.md
new file mode 100644
index 0000000..9f22fd1
--- /dev/null
+++ b/docs/document/usage/code-owners.md
@@ -0,0 +1,56 @@
+---
+date: "2023-05-24T16:00:00+00:00"
+slug: "code-owners"
+sidebar_position: 30
+aliases:
+  - /en-us/code-owners
+---
+
+# Code Owners
+
+Gitea maintains code owner files. It looks for it in the following locations in this order:
+
+- `./CODEOWNERS`
+- `./docs/CODEOWNERS`
+- `./.gitea/CODEOWNERS`
+
+And stops at the first found file.
+
+File format: `<regexp rule> <@user or @org/team> [@user or @org/team]...`
+
+Regexp specified in golang Regex format.
+Regexp can start with `!` for negative rules - match all files except specified.
+
+Example file:
+
+```bash
+.*\\.go @user1 @user2 # This is comment
+
+# Comment too
+# You can assigning code owning for users or teams
+frontend/src/.*\\.js @org1/team1 @org1/team2 @user3
+
+# You can use negative pattern
+!frontend/src/.* @org1/team3 @user5
+
+# You can use power of go regexp
+docs/(aws|google|azure)/[^/]*\\.(md|txt) @user8 @org1/team4
+!/assets/.*\\.(bin|exe|msi) @user9
+```
+
+### Escaping
+
+You can escape characters `#`, ` ` (space) and `\` with `\`, like:
+
+```
+dir/with\#hashtag @user1
+path\ with\ space @user2
+path/with\\backslash @user3
+```
+
+Some character (`.+*?()|[]{}^$\`) should be escaped with `\\` inside regexp, like:
+
+```
+path/\\.with\\.dots
+path/with\\+plus
+```
diff --git a/docs/document/usage/incoming-email.md b/docs/document/usage/incoming-email.md
new file mode 100644
index 0000000..c91d1ae
--- /dev/null
+++ b/docs/document/usage/incoming-email.md
@@ -0,0 +1,38 @@
+---
+date: "2023-05-23T09:00:00+08:00"
+
+slug: "incoming-email"
+sidebar_position: 13
+aliases:
+  - /zh-cn/incoming-email
+---
+
+# 邮件接收
+
+Gitea 支持通过接收邮件执行多种操作。本页面描述了如何进行设置。
+
+## 要求
+
+处理接收的电子邮件需要启用 IMAP 功能的电子邮件帐户。
+推荐的策略是使用 [电子邮件子地址](https://en.wikipedia.org/wiki/Email_address#Sub-addressing)，但也可以使用 catch-all 邮箱。
+接收电子邮件地址中包含一个用户/操作特定的令牌，告诉 Gitea 应执行哪个操作。
+此令牌应该出现在 `To` 和 `Delivered-To` 头字段中。
+
+Gitea 会尝试检测自动回复并跳过它们，电子邮件服务器也应该配置以减少接收到的干扰（垃圾邮件、通讯订阅等）。
+
+## 配置
+
+要激活处理接收的电子邮件消息功能，您需要在配置文件中配置 `email.incoming` 部分。
+
+`REPLY_TO_ADDRESS` 包含电子邮件客户端将要回复的地址。
+该地址需要包含 `%{token}` 占位符，该占位符将被替换为描述用户/操作的令牌。
+此占位符在地址中只能出现一次，并且必须位于地址的用户部分（`@` 之前）。
+
+使用电子邮件子地址的示例可能如下：`incoming+%{token}@example.com`
+
+如果使用 catch-all 邮箱，则占位符可以出现在地址的用户部分的任何位置：`incoming+%{token}@example.com`、`incoming_%{token}@example.com`、`%{token}@example.com`
+
+## 安全性
+
+在选择用于接收传入电子邮件的域时要小心。
+建议在子域名上接收传入电子邮件，例如 `incoming.example.com`，以防止与运行在 `example.com` 上的其他服务可能存在的安全问题。
diff --git a/docs/document/usage/issue-pull-request-templates.md b/docs/document/usage/issue-pull-request-templates.md
new file mode 100644
index 0000000..07dde74
--- /dev/null
+++ b/docs/document/usage/issue-pull-request-templates.md
@@ -0,0 +1,283 @@
+---
+date: "2022-09-07T16:00:00+08:00"
+slug: "issue-pull-request-templates"
+sidebar_position: 15
+toc: true
+aliases:
+  - /zh-cn/issue-pull-request-templates
+---
+
+# 从模板创建工单与合并请求
+
+开发者可以利用问题模板创建工单与合并请求，其目的在于规范参与者的语言表达。
+
+## 模板介绍
+
+Gitea 支持两种格式的模板：Markdown 和 YAML。
+
+### Markdown 模板
+
+在 Gitea 中存在两种用途的 Markdown 模板：
+
+- `ISSUE_TEMPLATE/bug-report.md` 用于规范工单的 Markdown 文本描述
+- `PULL_REQUEST_TEMPLATE.md` 用于规范合并请求的 Markdown 文本描述
+
+对于以上 Markdown 模板，我们推荐您将它们放置到项目目录 `.gitea` 进行收纳。
+
+### YAML 模板
+
+用 YAML 语法编写的模板相比 Markdown 可以实现更丰富的功能，利用表单实现诸如：问卷调查、字符校验。在 Gitea 中的 YAML 同样支持两种用途：
+
+- `ISSUE_TEMPLATE/bug-report.yaml` 用于创建问卷调查形式的工单
+- `PULL_REQUEST_TEMPLATE.yaml` 用于创建表单形式的合并请求
+
+对于以上 YAML 模板，我们同样推荐您将它们放置到项目目录 `.gitea` 进行收纳。
+
+##### 表单支持通过 URL 查询参数传值
+
+当新建工单页面 URL 以 `?title=Issue+Title&body=Issue+Text` 为查询参数，表单将使用其中的参数（key-value）填充表单内容。
+
+### Gitea 支持的模板文件路径
+
+工单模板文件名:
+
+- `ISSUE_TEMPLATE.md`
+- `ISSUE_TEMPLATE.yaml`
+- `ISSUE_TEMPLATE.yml`
+- `issue_template.md`
+- `issue_template.yaml`
+- `issue_template.yml`
+- `.gitea/ISSUE_TEMPLATE.md`
+- `.gitea/ISSUE_TEMPLATE.yaml`
+- `.gitea/ISSUE_TEMPLATE.yml`
+- `.gitea/issue_template.md`
+- `.gitea/issue_template.yaml`
+- `.gitea/issue_template.yml`
+- `.github/ISSUE_TEMPLATE.md`
+- `.github/ISSUE_TEMPLATE.yaml`
+- `.github/ISSUE_TEMPLATE.yml`
+- `.github/issue_template.md`
+- `.github/issue_template.yaml`
+- `.github/issue_template.yml`
+
+合并请求模板:
+
+- `PULL_REQUEST_TEMPLATE.md`
+- `PULL_REQUEST_TEMPLATE.yaml`
+- `PULL_REQUEST_TEMPLATE.yml`
+- `pull_request_template.md`
+- `pull_request_template.yaml`
+- `pull_request_template.yml`
+- `.gitea/PULL_REQUEST_TEMPLATE.md`
+- `.gitea/PULL_REQUEST_TEMPLATE.yaml`
+- `.gitea/PULL_REQUEST_TEMPLATE.yml`
+- `.gitea/pull_request_template.md`
+- `.gitea/pull_request_template.yaml`
+- `.gitea/pull_request_template.yml`
+- `.github/PULL_REQUEST_TEMPLATE.md`
+- `.github/PULL_REQUEST_TEMPLATE.yaml`
+- `.github/PULL_REQUEST_TEMPLATE.yml`
+- `.github/pull_request_template.md`
+- `.github/pull_request_template.yaml`
+- `.github/pull_request_template.yml`
+
+#### 工单模板目录
+
+由于工单存在多种类型，Gitea 支持将工单模板统一收纳到 `ISSUE_TEMPLATE` 目录。以下是 Gitea 支持的工单模板目录:
+
+- `ISSUE_TEMPLATE`
+- `issue_template`
+- `.gitea/ISSUE_TEMPLATE`
+- `.gitea/issue_template`
+- `.github/ISSUE_TEMPLATE`
+- `.github/issue_template`
+- `.gitlab/ISSUE_TEMPLATE`
+- `.gitlab/issue_template`
+
+目录支持混合存放 Markdown (`.md`) 或 YAML (`.yaml`/`.yml`) 格式的工单模板。另外，合并请求模板不支持目录存放。
+
+## Markdown 模板语法
+
+```md
+---
+name: "Template Name"
+about: "This template is for testing!"
+title: "[TEST] "
+ref: "main"
+labels:
+  - bug
+  - "help needed"
+---
+
+This is the template!
+```
+
+上面的示例表示用户从列表中选择一个工单模板时，列表会展示模板名称 `Template Name` 和模板描述 `This template is for testing!`。 同时，标题会预先填充为 `[TEST]`，而正文将预先填充 `This is the template!`。该 Issue 会被指派给 `user1`。 最后，Issue 还会被分配两个标签，`bug` 和 `help needed`，并且将问题指向 `main` 分支。
+
+## YAML 模板语法
+
+YAML 模板格式如下，相比 Markdown 模板提供了更多实用性的功能。
+
+```yaml
+name: 表单名称
+about: 表单描述
+title: 默认标题
+body: 主体内容
+  type: 定义表单元素类型
+    id: 定义表单标号
+    attributes: 扩展的属性
+    validations: 内容校验
+```
+
+下例 YAML 配置文件完整定义了一个用于提交 bug 的问卷调查。
+
+```yaml
+name: Bug Report
+about: File a bug report
+title: "[Bug]: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+  - type: input
+    id: contact
+    attributes:
+      label: Contact Details
+      description: How can we get in touch with you if we need more info?
+      placeholder: ex. email@example.com
+    validations:
+      required: false
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: Also tell us, what did you expect to happen?
+      placeholder: Tell us what you see!
+      value: "A bug happened!"
+    validations:
+      required: true
+  - type: dropdown
+    id: version
+    attributes:
+      label: Version
+      description: What version of our software are you running?
+      options:
+        - 1.0.2 (Default)
+        - 1.0.3 (Edge)
+    validations:
+      required: true
+  - type: dropdown
+    id: browsers
+    attributes:
+      label: What browsers are you seeing the problem on?
+      multiple: true
+      options:
+        - Firefox
+        - Chrome
+        - Safari
+        - Microsoft Edge
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant log output
+      description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
+      render: shell
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Code of Conduct
+      description: By submitting this issue, you agree to follow our [Code of Conduct](https://example.com)
+      options:
+        - label: I agree to follow this project's Code of Conduct
+          required: true
+```
+
+### Markdown 段落
+
+您可以在 YAML 模板中使用 `markdown` 元素为开发者提供额外的上下文支撑，这部分内容会作为创建工单的提示但不会作为工单内容提交。
+
+`attributes` 子项提供了以下扩展能力：
+
+| 键      | 描述                           | 必选 | 类型   | 默认值 | 有效值 |
+| ------- | ------------------------------ | ---- | ------ | ------ | ------ |
+| `value` | 渲染的文本。支持 Markdown 格式 | 必选 | 字符串 | -      | -      |
+
+### Textarea 多行文本输入框
+
+您可以使用 `textarea` 元素在表单中添加多行文本输入框。 除了输入文本，开发者还可以在 `textarea` 区域附加文件。
+
+`attributes` 子项提供了以下扩展能力：
+
+| 键            | 描述                                                                                                  | 必选 | 类型   | 默认值   | 有效值             |
+| ------------- | ----------------------------------------------------------------------------------------------------- | ---- | ------ | -------- | ------------------ |
+| `label`       | 预期用户输入的简短描述，也以表单形式显示。                                                            | 必选 | 字符串 | -        | -                  |
+| `description` | 提供上下文或指导的文本区域的描述，以表单形式显示。                                                    | 可选 | 字符串 | 空字符串 | -                  |
+| `placeholder` | 半透明的占位符，在文本区域空白时呈现                                                                  | 可选 | 字符串 | 空字符串 | -                  |
+| `value`       | 在文本区域中预填充的文本。                                                                            | 可选 | 字符串 | -        | -                  |
+| `render`      | 如果提供了值，提交的文本将格式化为代码块。 提供此键时，文本区域将不会扩展到文件附件或 Markdown 编辑。 | 可选 | 字符串 | -        | Gitea 支持的语言。 |
+
+`validations` 子项提供以下文本校验参数：
+
+| 键         | 描述                         | 必选 | 类型   | 默认值 | 有效值 |
+| ---------- | ---------------------------- | ---- | ------ | ------ | ------ |
+| `required` | 防止在元素完成之前提交表单。 | 可选 | 布尔型 | false  | -      |
+
+### Input 单行输入框
+
+您可以使用 `input` 元素添加单行文本字段到表单。
+
+`attributes` 子项提供了以下扩展能力：
+
+| 键            | 描述                                           | 必选 | 类型   | 默认值   | 有效值 |
+| ------------- | ---------------------------------------------- | ---- | ------ | -------- | ------ |
+| `label`       | 预期用户输入的简短描述，也以表单形式显示。     | 必选 | 字符串 | -        | -      |
+| `description` | 提供上下文或指导的字段的描述，以表单形式显示。 | 可选 | 字符串 | 空字符串 | -      |
+| `placeholder` | 半透明的占位符，在字段空白时呈现。             | 可选 | 字符串 | 空字符串 | -      |
+| `value`       | 字段中预填的文本。                             | 可选 | 字符串 | -        | -      |
+
+`validations` 子项提供以下文本校验参数：
+
+| 键          | 描述                             | 必选 | 类型   | 默认值 | 有效值                                                         |
+| ----------- | -------------------------------- | ---- | ------ | ------ | -------------------------------------------------------------- |
+| `required`  | 防止在未填内容时提交表单。       | 可选 | 布尔型 | false  | -                                                              |
+| `is_number` | 防止在未填数字时提交表单。       | 可选 | 布尔型 | false  | -                                                              |
+| `regex`     | 直到满足了与正则表达式匹配的值。 | 可选 | 字符串 | -      | [正则表达式](https://en.wikipedia.org/wiki/Regular_expression) |
+
+### Dropdown 下拉菜单
+
+您可以使用 `dropdown` 元素在表单中添加下拉菜单。
+
+`attributes` 子项提供了以下扩展能力：
+
+| 键            | 描述                                                      | 必选 | 类型       | 默认值   | 有效值 |
+| ------------- | --------------------------------------------------------- | ---- | ---------- | -------- | ------ |
+| `label`       | 预期用户输入的简短描述，以表单形式显示。                  | 必选 | 字符串     | -        | -      |
+| `description` | 提供上下文或指导的下拉列表的描述，以表单形式显示。        | 可选 | 字符串     | 空字符串 | -      |
+| `multiple`    | 确定用户是否可以选择多个选项。                            | 可选 | 布尔型     | false    | -      |
+| `options`     | 用户可以选择的选项列表。 不能为空，所有选择必须是不同的。 | 必选 | 字符串数组 | -        | -      |
+
+`validations` 子项提供以下文本校验参数：
+
+| 键         | 描述                         | 必选 | 类型   | 默认值 | 有效值 |
+| ---------- | ---------------------------- | ---- | ------ | ------ | ------ |
+| `required` | 防止在元素完成之前提交表单。 | 可选 | 布尔型 | false  | -      |
+
+### Checkboxes 复选框
+
+您可以使用 `checkboxes` 元素添加一组复选框到表单。
+
+`attributes` 子项提供了以下扩展能力：
+
+| 键            | 描述                                                  | 必选 | 类型   | 默认值   | 有效值 |
+| ------------- | ----------------------------------------------------- | ---- | ------ | -------- | ------ |
+| `label`       | 预期用户输入的简短描述，以表单形式显示。              | 必选 | 字符串 | -        | -      |
+| `description` | 复选框集的描述，以表单形式显示。 支持 Markdown 格式。 | 可选 | 字符串 | 空字符串 | -      |
+| `options`     | 用户可以选择的复选框列表。 有关语法，请参阅下文。     | 必选 | 数组   | -        | -      |
+
+对于 `options`，您可以设置以下参数：
+
+| 键         | 描述                                                                              | 必选 | 类型   | 默认值 | 有效值 |
+| ---------- | --------------------------------------------------------------------------------- | ---- | ------ | ------ | ------ |
+| `label`    | 选项的标识符，显示在表单中。 支持 Markdown 用于粗体或斜体文本格式化和超文本链接。 | 必选 | 字符串 | -      | -      |
+| `required` | 防止在元素完成之前提交表单。                                                      | 可选 | 布尔型 | false  | -      |
diff --git a/docs/document/usage/labels.md b/docs/document/usage/labels.md
new file mode 100644
index 0000000..05ce372
--- /dev/null
+++ b/docs/document/usage/labels.md
@@ -0,0 +1,33 @@
+---
+date: "2023-05-23T09:00:00+08:00"
+slug: "labels"
+sidebar_position: 13
+aliases:
+  - /zh-cn/labels
+---
+
+# 标签
+
+您可以使用标签对工单和合并请求进行分类，并提高对它们的概览。
+
+## 创建标签
+
+对于仓库，可以在 `工单（Issues）` 中点击 `标签（Labels）` 来创建标签。
+
+对于组织，您可以定义组织级别的标签，这些标签与所有组织仓库共享，包括已存在的仓库和新创建的仓库。可以在组织的 `设置（Settings）` 中创建组织级别的标签。
+
+标签具有必填的名称和颜色，可选的描述，以及必须是独占的或非独占的（见下面的“作用域标签”）。
+
+当您创建一个仓库时，可以通过使用 `工单标签（Issue Labels）` 选项来选择标签集。该选项列出了一些在您的实例上 [全局配置的可用标签集](../administration/customizing-gitea.md#labels)。在创建仓库时，这些标签也将被创建。
+
+## 作用域标签
+
+作用域标签用于确保将至多一个具有相同作用域的标签分配给工单或合并请求。例如，如果标签 `kind/bug` 和 `kind/enhancement` 的独占选项被设置，那么工单只能被分类为 bug 或 enhancement 中的一个。
+
+作用域标签的名称必须包含 `/`（不能在名称的任一端）。标签的作用域是基于最后一个 `/` 决定的，因此例如标签 `scope/subscope/item` 的作用域是 `scope/subscope`。
+
+## 按标签筛选
+
+工单和合并请求列表可以按标签进行筛选。选择多个标签将显示具有所有选定标签的工单和合并请求。
+
+通过按住 alt 键并单击标签，可以将具有所选标签的工单和合并请求从列表中排除。
diff --git a/docs/document/usage/linked-references.md b/docs/document/usage/linked-references.md
new file mode 100644
index 0000000..2d151d4
--- /dev/null
+++ b/docs/document/usage/linked-references.md
@@ -0,0 +1,143 @@
+---
+date: "2023-05-23T09:00:00+08:00"
+slug: "automatically-linked-references"
+sidebar_position: 15
+aliases:
+  - /zh-cn/automatically-linked-references
+---
+
+# 自动链接引用
+
+当发布工单、合并请求或评论时，文本描述会被解析以查找引用。这些引用将显示为工单视图中的链接，并且在某些情况下会触发特定的“操作”。
+
+类似地，当列出提交消息时，它们也会被解析，并且当它们被推送到主分支时可以触发“操作”。
+
+为了防止意外创建引用，对于引用的识别有一定的规则。例如，它们不应该包含在代码文本内部。它们还应该在周围的文本中合理清晰（例如，使用空格）。
+
+## 用户、团队和组织提及
+
+当找到形式为 `@username` 的文本，并且 `username` 与现有用户的名称匹配时，将创建一个“提及”引用。这将通过将文本更改为指向该用户个人资料的链接来显示，并根据被提及的用户是否具有访问内容所需的权限来可能创建通知。
+
+示例：
+
+> [@John](#)，你能看一下这个吗？
+
+对于团队和组织也是有效的：
+
+> [@Documenters](#)，我们需要为此进行规划。
+> [@CoolCompanyInc](#)，这个问题关系到我们所有人！
+
+团队将在适当时收到邮件通知，但整个组织不会收到通知。
+
+提交消息不会产生用户通知。
+
+## 提交
+
+可以使用提交的 SHA1 哈希或至少七个字符的一部分来引用提交。它们将显示为指向相应提交的链接。
+
+示例：
+
+> 这个错误是在 [e59ff077](#) 中引入的
+
+## 工单和合并请求
+
+可以使用简单的符号 `#1234` 来创建对另一个工单或合并请求的引用，其中 _1234_ 是同一仓库中一个工单或合并请求的编号。这些引用将显示为指向被引用内容的链接。
+
+创建此类型引用的效果是，在被引用的文档中创建一个“通知”，前提是引用的创建者对其具有读取权限。
+
+示例：
+
+> 这似乎与 [#1234](#) 相关
+
+还可以使用形式 `owner/repository#1234` 来引用其他仓库中的工单和合并请求：
+
+> 这似乎与 [mike/compiler#1234](#) 相关
+
+或者也可以使用 `!1234` 符号。虽然在 Gitea 中合并请求是工单的一种形式，但 `#1234` 形式总是链接到工单；如果链接的条目恰好是一个合并请求，Gitea 会适当地进行重定向。而使用 `!1234` 符号，则会创建一个合并请求链接，根据需要会被重定向到工单。然而，如果使用外部跟踪器，这个区别可能很重要，因为工单和合并请求的链接是不能互换的。
+
+## 可操作的引用在合并请求和提交消息中
+
+有时，一个提交或合并请求可能会修复或重新出现在某个特定工单中。Gitea 支持在引用之前加上特定的“关键字”来关闭和重新打开被引用的工单。常见的关键字包括“closes”、“fixes”、“reopens”等。这个列表可以由站点管理员进行 [自定义](../administration/config-cheat-sheet.md)。
+
+示例：
+
+> 这个合并请求 _closes_ [#1234](#)
+
+如果可操作的引用被接受，这将在被引用的工单上创建一个通知，宣布当引用的合并请求被合并时该工单将被关闭。
+
+为了接受可操作的引用，必须满足以下至少一项条件之一：
+
+- 评论者在创建引用时具有关闭或重新打开工单的权限。
+- 引用位于提交消息中。
+- 引用作为合并请求描述的一部分发布。
+
+在最后一种情况下，只有当合并合并请求的人具有相应权限时，工单才会被关闭或重新打开。
+
+此外，只有合并请求和提交消息可以创建一个操作，只有工单可以通过这种方式被关闭或重新打开。
+
+默认的关键字如下：
+
+- **关闭工单**: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved
+- **重新打开工单**: reopen, reopens, reopened
+
+## 合并请求和提交消息中的时间跟踪
+
+当提交或合并合并请求导致自动关闭工单时，还可以通过提交消息添加解决此工单所花费的时间。
+
+要指定解决工单所花费的时间，需要在工单编号后面以 `@<number><time-unit>` 的格式指定时间。在一个提交消息中，可以指定多个已解决的工单，并为每个工单指定花费的时间。
+
+支持的时间单位（`<time-unit>`）：
+
+- `m` - 分钟
+- `h` - 小时
+- `d` - 天（相当于 8 小时）
+- `w` - 周（相当于 5 天）
+- `mo` - 月（相当于 4 周）
+
+用于指定时间的数字（`<number>`）也可以是小数，例如 `@1.5h` 表示一小时半。多个时间单位可以结合使用，例如 `@1h10m` 表示 1 小时 10 分钟。
+
+提交消息示例：
+
+> Fixed #123 spent @1h, refs #102, fixes #124 @1.5h
+
+这将导致工单 #123 增加 1 小时，工单 #124 增加 1 小时半。
+
+## 外部跟踪器
+
+Gitea 支持使用外部工单跟踪器，并可以在合并请求中创建对外部托管的工单的引用。但是，如果外部跟踪器使用数字来标识工单，那么它们将与 Gitea 中托管的合并请求无法区分。为了解决这个问题，Gitea 允许使用 `!` 标记来标识合并请求。例如：
+
+> 这是工单 [#1234](#)，并链接到外部跟踪器。
+> 这是合并请求 [!1234](#)，并链接到 Gitea 中的合并请求。
+
+在工单和合并请求中，`!` 和 `#` 可以互换使用，除非需要进行区分。如果仓库使用外部跟踪器，默认情况下，合并提交消息将使用 `!` 作为引用。
+
+## 工单和合并请求引用摘要
+
+下表说明了工单和合并请求的不同类型的交叉引用。在示例中，`User1/Repo1` 指的是使用引用的仓库，而 `UserZ/RepoZ` 表示另一个仓库。
+
+| 在 User1/Repo1 中的引用 | Repo1 的工单是外部的 | RepoZ 的工单是外部的 | 渲染效果                                      |
+| ----------------------- | :------------------: | :------------------: | --------------------------------------------- |
+| `#1234`                 |          否          |          -           | 链接到 `User1/Repo1` 中的工单/合并请求 1234   |
+| `!1234`                 |          否          |          -           | 链接到 `User1/Repo1` 中的工单/合并请求 1234   |
+| `#1234`                 |          是          |          -           | 链接到 `User1/Repo1` 的 _外部工单_ 1234       |
+| `!1234`                 |          是          |          -           | 链接到 `User1/Repo1` 的 _PR_ 1234             |
+| `User1/Repo1#1234`      |          否          |          -           | 链接到 `User1/Repo1` 中的工单/合并请求 1234   |
+| `User1/Repo1!1234`      |          否          |          -           | 链接到 `User1/Repo1` 中的工单/合并请求 1234   |
+| `User1/Repo1#1234`      |          是          |          -           | 链接到 `User1/Repo1` 的 _外部工单_ 1234       |
+| `User1/Repo1!1234`      |          是          |          -           | 链接到 `User1/Repo1` 的 _PR_ 1234             |
+| `UserZ/RepoZ#1234`      |          -           |          否          | 链接到 `UserZ/RepoZ` 中的工单/合并请求 1234   |
+| `UserZ/RepoZ!1234`      |          -           |          否          | 链接到 `UserZ/RepoZ` 中的工单/合并请求 1234   |
+| `UserZ/RepoZ#1234`      |          -           |          是          | 链接到 `UserZ/RepoZ` 的 _外部工单_ 1234       |
+| `UserZ/RepoZ!1234`      |          -           |          是          | 链接到 `UserZ/RepoZ` 的 _PR_ 1234             |
+| **字母数字工单编号:**   |          -           |          -           | -                                             |
+| `AAA-1234`              |          是          |          -           | 链接到 `User1/Repo1` 的 _外部工单_ `AAA-1234` |
+| `!1234`                 |          是          |          -           | 链接到 `User1/Repo1` 的 _PR_ 1234             |
+| `User1/Repo1!1234`      |          是          |          -           | 链接到 `User1/Repo1` 的 _PR_ 1234             |
+| _不支持_                |          -           |          是          | 链接到 `UserZ/RepoZ` 的 _外部工单_ `AAA-1234` |
+| `UserZ/RepoZ!1234`      |          -           |          是          | 链接到 `UserZ/RepoZ` 中的 _PR_ 1234           |
+
+_最后一部分适用于使用字母数字格式的外部工单跟踪器的仓库。_
+
+_**-**: 不适用_
+
+注意：不完全支持具有不同类型工单（外部 vs. 内部）的仓库之间的自动引用，可能会导致无效链接。
diff --git a/docs/document/usage/markdown.md b/docs/document/usage/markdown.md
new file mode 100644
index 0000000..865bdae
--- /dev/null
+++ b/docs/document/usage/markdown.md
@@ -0,0 +1,102 @@
+---
+date: "2025-04-05T00:00:00+08:00"
+slug: "markdown"
+---
+
+# Markdown
+
+Gitea uses MarkDown structured text in many places, you can recognise it by the `.md` file extension.
+Markdown is plain text format for writing structured documents, allowing one to write
+"plain" text files that nonetheless have _"fancy"_ **formatting**, while still keeping the plain-text version readable.
+
+Unfortunately, due to historical implementation differences, many subtle dialects exist.
+To avoid adding to the confusion, Gitea tries to follow "[GitHub Flavoured Markdown (GFM)](https://help.github.com/articles/github-flavored-markdown/)" as close as possible.
+"GFM" is an extension on top of the rigorously-specified [CommonMark](https://commonmark.org/) standard.
+CommonMark flavours are used by most major web platforms (e.g. Reddit, Stack Overflow, Discourse)
+and git forges (GitHub, GitLab and our very own Gitea), thus you shouldn't run into any surprises with Gitea.
+
+For a quick introduction to the syntax and features of GitHub Flavoured Markdown, see the GitHub documentation:
+- [Basic formatting](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)
+- [Advanced formatting](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting)
+
+For a deeper history about CommonMark, its spec, and its reason for existence, see [CommonMark.org](https://commonmark.org/).
+
+## Rendering options
+
+Some Gitea's markdown rendering behaviors can be fine-tuned by global config options, see the `[markdown]` config section in the `app.example.ini`
+
+
+## Link path resolving
+
+When rendering links for `<a href>`, `<img src>` and `<video src>`, Gitea resolves the link paths in the rendering context.
+
+- If the link is an absolute path with scheme, the link is kept as-is.
+- If the link is an URL path, it is resolved with the base path of current rendering context.
+  - In a comment-like context (issues, pull-requests, commit message), the base path is current repository's home link: `/owner-name/repo-name`.
+  - In a repository file context (markdown files in the repository), the base path is current git ref path.
+
+### Special link tokens
+
+To make users easier to resolve a link to the Gitea instance's root path, Gitea has a special `/:root` path syntax.
+This will always resolve to Gitea's ROOT_URL.
+
+Gitea also supports GitHub's `?raw=1` query parameter.
+A request to `/owner-name/repo-name/src/branch/main/file?raw=1` will be redirected to
+`/owner-name/repo-name/raw/branch/main/file`. This makes it possible to target raw contents from relative links
+(normally, the `src/` section of the path is provided automatically by Gitea and cannot be overriden).
+
+### Link handling examples
+
+For example, when rendering a markdown file in `/owner-name/repo-name/src/branch/main/dir`:
+  1) Absolute with scheme: Link `https://example.org` will be rendered as-is.
+  2) Relative from current file: Link `sub/file`is resolved to `/owner-name/repo-name/src/branch/main/dir/sub/file`
+  3) Relative from repo root: Link `/sub/file` (note leading slash) is resolved to `/owner-name/repo-name/src/branch/main/sub/file`
+  4) Raw media: If the link is used as `src` of an image or video, then it is resolved to `/owner-name/repo-name/raw/...`
+  5) Raw relative: `sub/file?raw=1` will resolve to `/owner-name/repo-name/src/branch/main/dir/sub/file?raw=1`,
+    which will redirect to `/owner-name/repo-name/raw/branch/main/dir/sub/file`.
+  6) explicit root: Link `/:root/any-path` is always resolved to `$ROOT_URL/any-path` without any further processing.
+
+
+## Issue and pull-request reference
+
+Using issue/pull-request numbers in a list:
+
+```
+* #123
+* #456
+```
+
+It will be rendered with issue titles to:
+
+```
+* the issue title (#123)
+* the other issue title (#456)
+```
+
+## Math expressions
+
+Gitea supports GitHub-like math expression formatting.
+
+### Inline expression
+
+  - ``` $\alpha$ ```: quoted by single-dollar `$`
+  - ``` $$\alpha$$ ```: quoted by double-dollar `$$`
+  - ``` $`\alpha`$ ```: quoted by dollar with backquotes, the backquotes could repeat like normal code blocks.
+
+### Block expression
+
+Using `$$`:
+
+````
+$$
+\alpha
+$$
+````
+
+Using code-block with language:
+
+````
+```math
+\alpha
+```
+````
diff --git a/docs/document/usage/merge-message-templates.md b/docs/document/usage/merge-message-templates.md
new file mode 100644
index 0000000..ebfeab7
--- /dev/null
+++ b/docs/document/usage/merge-message-templates.md
@@ -0,0 +1,47 @@
+---
+date: "2023-05-23T09:00:00+08:00"
+slug: "merge-message-templates"
+sidebar_position: 15
+
+aliases:
+  - /zh-cn/merge-message-templates
+---
+
+# 合并消息模板
+
+## 文件名
+
+PR 默认合并消息模板可能的文件名：
+
+- `.gitea/default_merge_message/MERGE_TEMPLATE.md`
+- `.gitea/default_merge_message/REBASE_TEMPLATE.md`
+- `.gitea/default_merge_message/REBASE-MERGE_TEMPLATE.md`
+- `.gitea/default_merge_message/SQUASH_TEMPLATE.md`
+- `.gitea/default_merge_message/MANUALLY-MERGED_TEMPLATE.md`
+- `.gitea/default_merge_message/REBASE-UPDATE-ONLY_TEMPLATE.md`
+
+## 变量
+
+您可以在这些模板中使用以下以 `${}` 包围的变量，这些变量遵循 [os.Expand](https://pkg.go.dev/os#Expand) 语法：
+
+- BaseRepoOwnerName：此合并请求的基础仓库所有者名称
+- BaseRepoName：此合并请求的基础仓库名称
+- BaseBranch：此合并请求的基础仓库目标分支名称
+- HeadRepoOwnerName：此合并请求的源仓库所有者名称
+- HeadRepoName：此合并请求的源仓库名称
+- HeadBranch：此合并请求的源仓库分支名称
+- PullRequestTitle：合并请求的标题
+- PullRequestDescription：合并请求的描述
+- PullRequestPosterName：合并请求的提交者名称
+- PullRequestIndex：合并请求的索引号
+- PullRequestReference：合并请求的引用字符与索引号。例如，#1、!2
+- ClosingIssues：返回一个包含将由此合并请求关闭的所有工单的字符串。例如 `close #1, close #2`
+- ReviewedOn: 该提交所属的合并请求。例如： `Reviewed-on: https://gitea.com/foo/bar/pulls/1`
+- ReviewedBy: 谁同意的此合并请求。例如： `Reviewed-by: Jane Doe <jane.doe@example.com>`
+
+## 变基（Rebase）
+
+在没有合并提交的情况下进行变基时，`REBASE_TEMPLATE.md` 修改最后一次提交的消息。此模板还提供以下附加变量：
+
+- CommitTitle：提交的标题
+- CommitBody：提交的正文文本
diff --git a/docs/document/usage/migration.md b/docs/document/usage/migration.md
new file mode 100644
index 0000000..89221a3
--- /dev/null
+++ b/docs/document/usage/migration.md
@@ -0,0 +1,53 @@
+---
+date: "2024-09-11T09:30:00+08:00"
+slug: "migration"
+sidebar_position: 45
+---
+
+# Migration
+
+You can migrate repositories from other Git services to your Gitea instance.
+
+## How to migrate from Gogs/GitHub/GitLab to Gitea
+
+To migrate from Gogs to Gitea:
+
+- [Gogs version 0.11.46.0418](https://github.com/go-gitea/gitea/issues/4286)
+
+To migrate from GitHub to Gitea, you can use Gitea's built-in migration form.
+
+In order to migrate items such as issues, pull requests, etc. you will need to input at least your username.
+
+[Example (requires login)](https://demo.gitea.com/repo/migrate)
+
+To migrate from GitLab to Gitea, you can use this non-affiliated tool:
+
+https://github.com/loganinak/MigrateGitlabToGogs
+
+## How to migrate from AWS CodeCommit to Gitea
+
+- To use the AWS CodeCommit API, Gitea requires an access key ID and a secret access key. For security reasons, we recommend creating a new user with the minimum necessary permissions and generating an access key ID and secret access key for the migration. The minimum permissions required for this user are as follows:
+  ```
+  {
+    "Version": "2012-10-17",
+    "Statement": [
+      {
+        "Effect": "Allow",
+        "Action": [
+          "codecommit:GetRepository",
+          "codecommit:GitPull",
+          "codecommit:ListPullRequests",
+          "codecommit:GetPullRequest",
+          "codecommit:GetCommentsForPullRequest"
+        ],
+        "Resource": [
+          "arn:aws:codecommit:<region>:<account>:<Repo-to-Migrate>
+      }
+    ]
+  }
+  ```
+  - If you do not need to migrate pull requests, you can remove the `ListPullRequests`, `GetPullRequest`, and `GetCommentsForPullRequest` actions.
+
+  - For instructions on how to create an IAM user and assign permissions, you can refer to this [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html).
+
+- To clone this repository, Gitea requires HTTPS Git credentials. You can create HTTPS Git credentials according to this [AWS documentation](https://docs.aws.amazon.com/codecommit/latest/userguide/setting-up-gc.html).
diff --git a/docs/document/usage/multi-factor-authentication.md b/docs/document/usage/multi-factor-authentication.md
new file mode 100644
index 0000000..c9680b7
--- /dev/null
+++ b/docs/document/usage/multi-factor-authentication.md
@@ -0,0 +1,28 @@
+---
+date: "2023-08-22T14:21:00+08:00"
+slug: "multi-factor-authentication"
+weight: 15
+---
+
+# Multi-factor Authentication (MFA)
+
+Multi-factor Authentication (also referred to as MFA or 2FA) enhances security by requiring a time-sensitive set of credentials in addition to a password.
+If a password were later to be compromised, logging into Gitea will not be possible without the additional credentials and the account would remain secure.
+Gitea supports both TOTP (Time-based One-Time Password) tokens and FIDO-based hardware keys using the Webauthn API.
+
+MFA can be configured within the "Security" tab of the user settings page.
+
+## MFA Considerations
+
+Enabling MFA on a user does affect how the Git HTTP protocol can be used with the Git CLI.
+This interface does not support MFA, and trying to use a password normally will no longer be possible whilst MFA is enabled.
+If SSH is not an option for Git operations, an access token can be generated within the "Applications" tab of the user settings page.
+This access token can be used as if it were a password in order to allow the Git CLI to function over HTTP.
+
+:::warning
+By its very nature, an access token sidesteps the security benefits of MFA.
+It must be kept secure and should only be used as a last resort.
+:::
+
+The Gitea API supports providing the relevant TOTP password in the `X-Gitea-OTP` header, as described in [API Usage](development/api-usage.md).
+This should be used instead of an access token where possible.
diff --git a/docs/document/usage/packages/alpine.md b/docs/document/usage/packages/alpine.md
new file mode 100644
index 0000000..f62f48e
--- /dev/null
+++ b/docs/document/usage/packages/alpine.md
@@ -0,0 +1,121 @@
+---
+date: "2023-03-25T00:00:00+00:00"
+slug: "alpine"
+sidebar_position: 4
+---
+
+# Alpine 软件包注册表
+
+在您的用户或组织中发布 [Alpine](https://pkgs.alpinelinux.org/) 软件包。
+
+## 要求
+
+要使用 Alpine 注册表，您需要使用像 curl 这样的 HTTP 客户端来上传包，并使用像 apk 这样的包管理器来消费包。
+
+以下示例使用 `apk`。
+
+## 配置软件包注册表
+
+要注册 Alpine 注册表，请将 URL 添加到已知的 apk 源列表中 (`/etc/apk/repositories`):
+
+```
+https://gitea.example.com/api/packages/{owner}/alpine/<branch>/<repository>
+```
+
+| 占位符       | 描述           |
+| ------------ | -------------- |
+| `owner`      | 软件包所有者   |
+| `branch`     | 要使用的分支名 |
+| `repository` | 要使用的仓库名 |
+
+如果注册表是私有的，请在 URL 中提供凭据。您可以使用密码或[个人访问令牌](development/api-usage.md#通过-api-认证):
+
+```
+https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/alpine/<branch>/<repository>
+```
+
+Alpine 注册表文件使用 RSA 密钥进行签名，apk 必须知道该密钥。下载公钥并将其存储在 `/etc/apk/keys/` 目录中：
+
+```shell
+curl -JO https://gitea.example.com/api/packages/{owner}/alpine/key
+```
+
+之后，更新本地软件包索引：
+
+```shell
+apk update
+```
+
+## 发布软件包
+
+要发布一个 Alpine 包（`*.apk`），请执行带有包内容的 HTTP `PUT` 操作，将其放在请求体中。
+
+```
+PUT https://gitea.example.com/api/packages/{owner}/alpine/{branch}/{repository}
+```
+
+| 参数         | 描述                                                                                                |
+| ------------ | --------------------------------------------------------------------------------------------------- |
+| `owner`      | 包的所有者。                                                                                        |
+| `branch`     | 分支可以与操作系统的发行版本匹配，例如：v3.17。                                                     |
+| `repository` | 仓库可以用于[分组包](https://wiki.alpinelinux.org/wiki/Repositories) 或者只是 `main` 或类似的名称。 |
+
+使用 HTTP 基本身份验证的示例请求：
+
+```shell
+curl --user your_username:your_password_or_token \
+     --upload-file path/to/file.apk \
+     https://gitea.example.com/api/packages/testuser/alpine/v3.17/main
+```
+
+如果您使用的是双重身份验证或 OAuth，请使用[个人访问令牌](development/api-usage.md#authentication)代替密码。
+您不能将具有相同名称的文件两次发布到一个包中。您必须首先删除现有的包文件。
+
+服务器将以以下的 HTTP 状态码响应：
+
+| HTTP 状态码       | 含义                                       |
+| ----------------- | ------------------------------------------ |
+| `201 Created`     | 软件包已发布。                             |
+| `400 Bad Request` | 软件包的名称、版本、分支、仓库或架构无效。 |
+| `409 Conflict`    | 具有相同参数组合的包文件已存在于软件包中。 |
+
+## 删除软件包
+
+要删除 Alpine 包，执行 HTTP 的 DELETE 操作。如果没有文件，这将同时删除包版本。
+
+```
+DELETE https://gitea.example.com/api/packages/{owner}/alpine/{branch}/{repository}/{architecture}/{filename}
+```
+
+| 参数           | 描述           |
+| -------------- | -------------- |
+| `owner`        | 软件包的所有者 |
+| `branch`       | 要使用的分支名 |
+| `repository`   | 要使用的仓库名 |
+| `architecture` | 软件包的架构   |
+| `filename`     | 要删除的文件名 |
+
+使用 HTTP 基本身份验证的示例请求：
+
+```shell
+curl --user your_username:your_token_or_password -X DELETE \
+     https://gitea.example.com/api/packages/testuser/alpine/v3.17/main/test-package-1.0.0.apk
+```
+
+服务器将以以下的 HTTP 状态码响应：
+
+| HTTP 状态码      | 含义               |
+| ---------------- | ------------------ |
+| `204 No Content` | 成功               |
+| `404 Not Found`  | 未找到软件包或文件 |
+
+## 安装软件包
+
+要从 Alpine 注册表安装软件包，请执行以下命令：
+
+```shell
+# use latest version
+apk add {package_name}
+# use specific version
+apk add {package_name}={package_version}
+```
diff --git a/docs/document/usage/packages/arch.md b/docs/document/usage/packages/arch.md
new file mode 100644
index 0000000..7369f9c
--- /dev/null
+++ b/docs/document/usage/packages/arch.md
@@ -0,0 +1,132 @@
+---
+date: "2023-05-15T00:00:00+00:00"
+slug: "arch"
+sidebar_position: 5
+---
+
+# Arch package registry
+
+Publish [Arch](https://archlinux.org/packages/) packages for your user or organization. The registry can act as a fully working [Arch linux mirror](https://wiki.archlinux.org/title/mirrors) connected directly in `/etc/pacman.conf`.
+
+## Requirements
+
+To work with the Arch registry, you need to use a HTTP client like `curl` to upload and a package manager like `pacman` to consume packages.
+
+The following examples use `pacman`.
+
+## Configuring the package registry
+
+Before you can use the package registry, you need to download the package verification key and add the registry to the pacman config.
+
+Download the package verification key.
+```sh
+wget https://gitea.example.com/api/packages/{owner}/arch/repository.key
+```
+
+Display the id the key (the long line with hex characters).
+```sh
+gpg --show-keys repository.key
+```
+
+Add the key to pacman and sign it (use the key id from the previous step).
+```sh
+pacman-key --add repository.key
+pacman-key --lsign-key {key id}
+```
+
+Now add the registry configuration to `/etc/pacman.conf`.
+```conf
+[{owner}.gitea.example.com]
+SigLevel = Required
+Server = https://gitea.example.com/api/packages/{owner}/arch/{repository}/{architecture}
+```
+
+| Placeholder    | Description |
+| -------------- | ----------- |
+| `owner`        | The owner of the packages. |
+| `repository`   | The repository to use. |
+| `architecture` | The architecture to use. |
+
+Consult the owners package overview to see what `repository` and `architecture` is available.
+
+If the registry is private, provide credentials in the url. You can use a password or a [personal access token](development/api-usage.md#authentication):
+
+```
+Server = https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/arch/{repository}/{architecture}
+```
+
+## Publish a package
+
+To publish an Arch package, perform a HTTP `PUT` operation with the package content in the request body.
+
+```
+PUT https://gitea.example.com/api/packages/{owner}/arch/{repository}
+```
+
+| Parameter    | Description |
+| ------------ | ----------- |
+| `owner`      | The owner of the package. |
+| `repository` | The repository can be used to group packages or just `core` or similar. |
+
+Example request using HTTP Basic authentication:
+
+```shell
+curl --user your_username:your_password_or_token \
+     --upload-file path/to/file.pkg.tar.zst \
+     https://gitea.example.com/api/packages/testuser/arch/core
+```
+
+If you are using 2FA or OAuth use a [personal access token](development/api-usage.md#authentication) instead of the password.
+
+You cannot publish a file with the same name twice to a package. You must delete the existing package file first.
+
+The server responds with the following HTTP Status codes.
+
+| HTTP Status Code  | Meaning |
+| ----------------- | ------- |
+| `201 Created`     | The package has been published. |
+| `400 Bad Request` | Something of the package is invalid. The error message contains more information. |
+| `409 Conflict`    | A package file with the same combination of parameters exist already in the package. |
+
+## Install packages
+
+To install a package run the pacman sync command:
+
+```sh
+pacman -Sy {package_name}
+```
+
+| Parameter      | Description |
+| -------------- | ----------- |
+| `package_name` | The package name. |
+
+## Delete a package
+
+To delete an Arch package perform a HTTP `DELETE` operation. This will delete the package version too if there is no file left.
+
+```
+DELETE https://gitea.example.com/api/packages/{owner}/arch/{repository}/{package_name}/{package_version}/{architecture}
+```
+
+| Parameter         | Description |
+| ----------------- | ----------- |
+| `owner`           | The owner of the package. |
+| `repository`      | The repository to use. |
+| `architecture`    | The package architecture. |
+| `package_name`    | The package name. |
+| `package_version` | The package version. |
+
+
+Example request using HTTP Basic authentication:
+
+```shell
+curl --user your_username:your_token_or_password -X DELETE \
+     https://gitea.example.com/api/packages/testuser/arch/core/test-package/1.0.0/x86-64
+```
+
+The server responds with the following HTTP Status codes.
+
+| HTTP Status Code  | Meaning |
+| ----------------- | ------- |
+| `204 No Content`  | Success |
+| `404 Not Found`   | The package or file was not found. |
diff --git a/docs/document/usage/packages/cargo.md b/docs/document/usage/packages/cargo.md
new file mode 100644
index 0000000..e1d18bd
--- /dev/null
+++ b/docs/document/usage/packages/cargo.md
@@ -0,0 +1,98 @@
+---
+date: "2022-11-20T00:00:00+00:00"
+slug: "cargo"
+sidebar_position: 5
+---
+
+# Cargo 软件包注册表
+
+为您的用户或组织发布 [Cargo](https://doc.rust-lang.org/stable/cargo/) 软件包。
+
+## 要求
+
+若要使用 Cargo 软件包注册表, 您需要安装 [Rust 和 Cargo](https://www.rust-lang.org/tools/install).
+
+Cargo 将可用软件包的信息存储在一个存储在 git 仓库中的软件包索引中。
+这个仓库是与注册表交互所必需的。
+下面的部分将介绍如何创建它。
+
+## 索引仓库
+
+Cargo 将可用软件包的信息存储在一个存储在 git 仓库中的软件包索引中。
+在 Gitea 中，这个仓库有一个特殊的名称叫做 `_cargo-index`。
+在上传软件包之后，它的元数据会自动写入索引中。
+不应手动修改这个注册表的内容。
+
+用户或组织软件包设置页面允许创建这个索引仓库以及配置文件。
+如果需要，此操作将重写配置文件。
+例如，如果 Gitea 实例的域名已更改，这将非常有用。
+
+如果存储在 Gitea 中的软件包与索引注册表中的信息不同步，设置页面允许重建这个索引注册表。
+这个操作将遍历注册表中的所有软件包，并将它们的信息写入索引中。
+如果有很多软件包，这个过程可能需要一些时间。
+
+## 配置软件包注册表
+
+要注册这个软件包注册表，必须更新 Cargo 的配置。
+将以下文本添加到位于当前用户主目录中的配置文件中（例如 `~/.cargo/config.toml`）：
+
+```
+[registry]
+default = "gitea"
+
+[registries.gitea]
+index = "sparse+https://gitea.example.com/api/packages/{owner}/cargo/" # Sparse index
+# index = "https://gitea.example.com/{owner}/_cargo-index.git" # Git
+
+[net]
+git-fetch-with-cli = true
+```
+
+| 参数    | 描述             |
+| ------- | ---------------- |
+| `owner` | 软件包的所有者。 |
+
+如果这个注册表是私有的或者您想要发布新的软件包，您必须配置您的凭据。
+将凭据部分添加到位于当前用户主目录中的凭据文件中（例如 `~/.cargo/credentials.toml`）：
+
+```
+[registries.gitea]
+token = "Bearer {token}"
+```
+
+| 参数    | 描述                                                                                  |
+| ------- | ------------------------------------------------------------------------------------- |
+| `token` | 您的[个人访问令牌](development/api-usage.md#通过-api-认证) |
+
+## 发布软件包
+
+在项目中运行以下命令来发布软件包：
+
+```shell
+cargo publish
+```
+
+如果已经存在同名和版本的软件包，您将无法发布新的软件包。您必须先删除现有的软件包。
+
+## 安装软件包
+
+要从软件包注册表安装软件包，请执行以下命令：
+
+```shell
+cargo add {package_name}
+```
+
+| 参数           | 描述         |
+| -------------- | ------------ |
+| `package_name` | 软件包名称。 |
+
+## 支持的命令
+
+```
+cargo publish
+cargo add
+cargo install
+cargo yank
+cargo unyank
+cargo search
+```
diff --git a/docs/document/usage/packages/chef.md b/docs/document/usage/packages/chef.md
new file mode 100644
index 0000000..94933e2
--- /dev/null
+++ b/docs/document/usage/packages/chef.md
@@ -0,0 +1,84 @@
+---
+date: "2023-01-20T00:00:00+00:00"
+slug: "chef"
+sidebar_position: 5
+---
+
+# Chef 软件包注册表
+
+为您的用户或组织发布 [Chef](https://chef.io/) cookbooks。
+
+## 要求
+
+要使用 Chef 软件包注册表，您需要使用 [`knife`](https://docs.chef.io/workstation/knife/).
+
+## 认证
+
+Chef 软件包注册表不使用用户名和密码进行身份验证，而是使用私钥和公钥对请求进行签名。
+请访问软件包所有者设置页面以创建必要的密钥对。
+只有公钥存储在Gitea中。如果您丢失了私钥的访问权限，您必须重新生成密钥对。
+[配置 `knife`](https://docs.chef.io/workstation/knife_setup/)，使用下载的私钥，并将 Gitea 用户名设置为 `client_name`。
+
+## 配置软件包注册表
+
+要将 [`knife` 配置](https://docs.chef.io/workstation/knife_setup/)为使用 Gitea 软件包注册表，请将 URL 添加到 `~/.chef/config.rb` 文件中。
+
+```
+knife[:supermarket_site] = 'https://gitea.example.com/api/packages/{owner}/chef'
+```
+
+| 参数    | 描述           |
+| ------- | -------------- |
+| `owner` | 软件包的所有者 |
+
+## 发布软件包
+
+若要发布 Chef 软件包，请执行以下命令：
+
+```shell
+knife supermarket share {package_name}
+```
+
+| 参数           | 描述       |
+| -------------- | ---------- |
+| `package_name` | 软件包名称 |
+
+如果已经存在同名和版本的软件包，则无法发布新的软件包。您必须先删除现有的软件包。
+
+## 安装软件包
+
+要从软件包注册表中安装软件包，请执行以下命令：
+
+```shell
+knife supermarket install {package_name}
+```
+
+您可以指定软件包的版本，这是可选的：
+
+```shell
+knife supermarket install {package_name} {package_version}
+```
+
+| 参数              | 描述       |
+| ----------------- | ---------- |
+| `package_name`    | 软件包名称 |
+| `package_version` | 软件包版本 |
+
+## 删除软件包
+
+如果您想要从注册表中删除软件包，请执行以下命令：
+
+```shell
+knife supermarket unshare {package_name}
+```
+
+可选地，您可以指定软件包的版本：
+
+```shell
+knife supermarket unshare {package_name}/versions/{package_version}
+```
+
+| 参数              | 描述       |
+| ----------------- | ---------- |
+| `package_name`    | 软件包名称 |
+| `package_version` | 软件包版本 |
diff --git a/docs/document/usage/packages/composer.md b/docs/document/usage/packages/composer.md
new file mode 100644
index 0000000..464d1da
--- /dev/null
+++ b/docs/document/usage/packages/composer.md
@@ -0,0 +1,110 @@
+---
+date: "2021-07-20T00:00:00+00:00"
+slug: "composer"
+sidebar_position: 10
+---
+
+# Composer 软件包注册表
+
+为您的用户或组织发布 [Composer](https://getcomposer.org/) 软件包。
+
+## 要求
+
+要使用 Composer 软件包注册表，您可以使用 [Composer](https://getcomposer.org/download/) 消费，并使用类似 `curl` 的 HTTP 上传客户端发布软件包。
+
+## 发布软件包
+
+要发布 Composer 软件包，请执行 HTTP `PUT` 操作，将软件包内容放入请求体中。
+软件包内容必须是包含 `composer.json` 文件的压缩 PHP 项目。
+如果已经存在同名和版本的软件包，则无法发布新的软件包。您必须先删除现有的软件包。
+
+```
+PUT https://gitea.example.com/api/packages/{owner}/composer
+```
+
+| 参数    | 描述           |
+| ------- | -------------- |
+| `owner` | 软件包的所有者 |
+
+如果 `composer.json` 文件不包含 `version` 属性，您必须将其作为查询参数提供：
+
+```
+PUT https://gitea.example.com/api/packages/{owner}/composer?version={x.y.z}
+```
+
+使用 HTTP 基本身份验证的示例请求：
+
+```shell
+curl --user your_username:your_password_or_token \
+     --upload-file path/to/project.zip \
+     https://gitea.example.com/api/packages/testuser/composer
+```
+
+或者将软件包版本指定为查询参数：
+
+```shell
+curl --user your_username:your_password_or_token \
+     --upload-file path/to/project.zip \
+     https://gitea.example.com/api/packages/testuser/composer?version=1.0.3
+```
+
+如果您使用 2FA 或 OAuth，请使用[个人访问令牌](development/api-usage.md#通过-api-认证)替代密码。
+
+服务器将以以下 HTTP 状态码响应。
+
+| HTTP 状态码       | 含义                                                        |
+| ----------------- | ----------------------------------------------------------- |
+| `201 Created`     | 软件包已发布                                                |
+| `400 Bad Request` | 软件包名称和/或版本无效，或具有相同名称和版本的软件包已存在 |
+
+## 配置软件包注册表
+
+要注册软件包注册表，您需要将其添加到 Composer 的 `config.json` 文件中（通常可以在 `<user-home-dir>/.composer/config.json` 中找到）：
+
+```json
+{
+  "repositories": [{
+      "type": "composer",
+      "url": "https://gitea.example.com/api/packages/{owner}/composer"
+   }
+  ]
+}
+```
+
+要使用凭据访问软件包注册表，您必须在 `auth.json` 文件中指定它们，如下所示：
+
+```json
+{
+  "http-basic": {
+    "gitea.example.com": {
+      "username": "{username}",
+      "password": "{password}"
+    }
+  }
+}
+```
+
+| 参数       | 描述                        |
+| ---------- | --------------------------- |
+| `owner`    | 软件包的所有者              |
+| `username` | 您的 Gitea 用户名           |
+| `password` | 您的Gitea密码或个人访问令牌 |
+
+## 安装软件包
+
+要从软件包注册表中安装软件包，请执行以下命令：
+
+```shell
+composer require {package_name}
+```
+
+您可以指定软件包的版本，这是可选的：
+
+```shell
+composer require {package_name}:{package_version}
+```
+
+| 参数              | 描述       |
+| ----------------- | ---------- |
+| `package_name`    | 软件包名称 |
+| `package_version` | 软件包版本 |
diff --git a/docs/document/usage/packages/conan.md b/docs/document/usage/packages/conan.md
new file mode 100644
index 0000000..b5a3782
--- /dev/null
+++ b/docs/document/usage/packages/conan.md
@@ -0,0 +1,89 @@
+---
+date: "2021-07-20T00:00:00+00:00"
+slug: "conan"
+sidebar_position: 20
+---
+
+# Conan 软件包注册表
+
+为您的用户或组织发布 [Conan](https://conan.io/) 软件包。
+
+## 要求
+
+要使用 [conan](https://conan.io/downloads.html) 软件包注册表，您需要使用 conan 命令行工具来消费和发布软件包。
+
+## 配置软件包注册表
+
+要注册软件包注册表，您需要配置一个新的 Conan remote：
+
+```shell
+conan remote add {remote} https://gitea.example.com/api/packages/{owner}/conan
+conan user --remote {remote} --password {password} {username}
+```
+
+| 参数       | 描述                                                                                                                                        |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `remote`   | 远程名称。                                                                                                                                  |
+| `username` | 您的 Gitea 用户名。                                                                                                                         |
+| `password` | 您的 Gitea 密码。如果您使用 2FA 或 OAuth，请使用[个人访问令牌](development/api-usage.md#通过-api-认证)替代密码。 |
+| `owner`    | 软件包的所有者。                                                                                                                            |
+
+例如:
+
+```shell
+conan remote add gitea https://gitea.example.com/api/packages/testuser/conan
+conan user --remote gitea --password password123 testuser
+```
+
+## 发布软件包
+
+通过运行以下命令发布 Conan 软件包：
+
+```shell
+conan upload --remote={remote} {recipe}
+```
+
+| 参数     | 描述            |
+| -------- | --------------- |
+| `remote` | 远程名称        |
+| `recipe` | 要上传的 recipe |
+
+For example:
+
+```shell
+conan upload --remote=gitea ConanPackage/1.2@gitea/final
+```
+
+Gitea Conan 软件包注册表支持完整的[版本修订](https://docs.conan.io/en/latest/versioning/revisions.html)。
+
+## 安装软件包
+
+要从软件包注册表中安装Conan软件包，请执行以下命令：
+
+```shell
+conan install --remote={remote} {recipe}
+```
+
+| 参数     | 描述            |
+| -------- | --------------- |
+| `remote` | 远程名称        |
+| `recipe` | 要下载的 recipe |
+
+例如：
+
+```shell
+conan install --remote=gitea ConanPackage/1.2@gitea/final
+```
+
+## 支持的命令
+
+```
+conan install
+conan get
+conan info
+conan search
+conan upload
+conan user
+conan download
+conan remove
+```
diff --git a/docs/document/usage/packages/conda.md b/docs/document/usage/packages/conda.md
new file mode 100644
index 0000000..4856143
--- /dev/null
+++ b/docs/document/usage/packages/conda.md
@@ -0,0 +1,73 @@
+---
+date: "2022-12-28T00:00:00+00:00"
+slug: "conda"
+sidebar_position: 25
+---
+
+# Conda 软件包注册表
+
+为您的用户或组织发布 [Conda](https://docs.conda.io/en/latest/) 软件包。
+
+## 要求
+
+要使用 Conda 软件包注册表，您需要使用 [conda](https://docs.conda.io/projects/conda/en/stable/user-guide/install/index.html) 命令行工具。
+
+## 配置软件包注册表
+
+要注册软件包注册表并提供凭据，请编辑您的 `.condarc` 文件：
+
+```yaml
+channel_alias: https://gitea.example.com/api/packages/{owner}/conda
+channels:
+  - https://gitea.example.com/api/packages/{owner}/conda
+default_channels:
+  - https://gitea.example.com/api/packages/{owner}/conda
+```
+
+| 占位符  | 描述           |
+| ------- | -------------- |
+| `owner` | 软件包的所有者 |
+
+有关各个设置的解释，请参阅[官方文档](https://conda.io/projects/conda/en/latest/user-guide/configuration/use-condarc.html)。
+
+如果需要提供凭据，可以将它们作为通道 URL 的一部分嵌入（`https://user:password@gitea.example.com/...`）。
+
+## 发布软件包
+
+要发布一个软件包，请执行一个HTTP `PUT`操作，请求正文中包含软件包内容。
+
+```
+PUT https://gitea.example.com/api/packages/{owner}/conda/{channel}/{filename}
+```
+
+| 占位符     | 描述                                                                                                |
+| ---------- | --------------------------------------------------------------------------------------------------- |
+| `owner`    | 软件包的所有者                                                                                      |
+| `channel`  | 软件包的[通道](https://conda.io/projects/conda/en/latest/user-guide/concepts/channels.html)（可选） |
+| `filename` | 文件名                                                                                              |
+
+使用HTTP基本身份验证的示例请求：
+
+```shell
+curl --user your_username:your_password_or_token \
+     --upload-file path/to/package-1.0.conda \
+     https://gitea.example.com/api/packages/testuser/conda/package-1.0.conda
+```
+
+如果已经存在同名和版本的软件包，则无法发布软件包。您必须先删除现有的软件包。
+
+## 安装软件包
+
+要从软件包注册表中安装软件包，请执行以下命令之一：
+
+```shell
+conda install {package_name}
+conda install {package_name}={package_version}
+conda install -c {channel} {package_name}
+```
+
+| 参数              | 描述                 |
+| ----------------- | -------------------- |
+| `package_name`    | 软件包的名称         |
+| `package_version` | 软件包的版本         |
+| `channel`         | 软件包的通道（可选） |
diff --git a/docs/document/usage/packages/container.md b/docs/document/usage/packages/container.md
new file mode 100644
index 0000000..4fef035
--- /dev/null
+++ b/docs/document/usage/packages/container.md
@@ -0,0 +1,81 @@
+---
+date: "2021-07-20T00:00:00+00:00"
+slug: "container"
+sidebar_position: 30
+---
+
+# 容器注册表
+
+为您的用户或组织发布符合  [Open Container Initiative(OCI)](https://opencontainers.org/) 规范的镜像。
+该容器注册表遵循 OCI 规范，并支持所有兼容的镜像类型，如 [Docker](https://www.docker.com/) 和 [Helm Charts](https://helm.sh/)。
+
+## 目录
+
+要使用容器注册表，您可以使用适用于特定镜像类型的工具。
+以下示例使用 `docker` 客户端。
+
+## 登录容器注册表
+
+要推送镜像或者如果镜像位于私有注册表中，您需要进行身份验证：
+
+```shell
+docker login gitea.example.com
+```
+
+如果您使用的是 2FA 或 OAuth，请使用[个人访问令牌](development/api-usage.md#通过-api-认证)替代密码进行身份验证。
+
+## 镜像命名约定
+
+镜像必须遵循以下命名约定：
+
+`{registry}/{owner}/{image}`
+
+例如，以下是所有者为 `testuser` 的有效镜像名称示例：
+
+`gitea.example.com/testuser/myimage`
+
+`gitea.example.com/testuser/my-image`
+
+`gitea.example.com/testuser/my/image`
+
+**注意:** 该注册表仅支持大小写不敏感的标签名称。因此，`image:tag` 和 `image:Tag` 将被视为相同的镜像和标签。
+
+## 推送镜像
+
+通过执行以下命令来推送镜像：
+
+```shell
+docker push gitea.example.com/{owner}/{image}:{tag}
+```
+
+| 参数    | 描述         |
+| ------- | ------------ |
+| `owner` | 镜像的所有者 |
+| `image` | 镜像的名称   |
+| `tag`   | 镜像的标签   |
+
+例如：
+
+```shell
+docker push gitea.example.com/testuser/myimage:latest
+```
+
+## 拉取镜像
+
+通过执行以下命令来拉取镜像：
+
+```shell
+docker pull gitea.example.com/{owner}/{image}:{tag}
+```
+
+| Parameter | Description  |
+| --------- | ------------ |
+| `owner`   | 镜像的所有者 |
+| `image`   | 镜像的名称   |
+| `tag`     | 镜像的标签   |
+
+例如：
+
+```shell
+docker pull gitea.example.com/testuser/myimage:latest
+```
diff --git a/docs/document/usage/packages/cran.md b/docs/document/usage/packages/cran.md
new file mode 100644
index 0000000..bf7b27e
--- /dev/null
+++ b/docs/document/usage/packages/cran.md
@@ -0,0 +1,81 @@
+---
+date: "2023-01-01T00:00:00+00:00"
+slug: "cran"
+sidebar_position: 35
+---
+
+# CRAN 软件包注册表
+
+将 [R](https://www.r-project.org/) 软件包发布到您的用户或组织的类似 [CRAN](https://cran.r-project.org/) 的注册表。
+
+## 要求
+
+要使用CRAN软件包注册表，您需要安装 [R](https://cran.r-project.org/)。
+
+## 配置软件包注册表
+
+要注册软件包注册表，您需要将其添加到 `Rprofile.site` 文件中，可以是系统级别、用户级别 `~/.Rprofile` 或项目级别：
+
+```
+options("repos" = c(getOption("repos"), c(gitea="https://gitea.example.com/api/packages/{owner}/cran")))
+```
+
+| 参数    | 描述           |
+| ------- | -------------- |
+| `owner` | 软件包的所有者 |
+
+如果需要提供凭据，可以将它们嵌入到URL(`https://user:password@gitea.example.com/...`)中。
+
+## 发布软件包
+
+要发布 R 软件包，请执行带有软件包内容的 HTTP `PUT` 操作。
+
+源代码软件包：
+
+```
+PUT https://gitea.example.com/api/packages/{owner}/cran/src
+```
+
+| 参数    | 描述           |
+| ------- | -------------- |
+| `owner` | 软件包的所有者 |
+
+二进制软件包：
+
+```
+PUT https://gitea.example.com/api/packages/{owner}/cran/bin?platform={platform}&rversion={rversion}
+```
+
+| 参数       | 描述           |
+| ---------- | -------------- |
+| `owner`    | 软件包的所有者 |
+| `platform` | 平台的名称     |
+| `rversion` | 二进制的R版本  |
+
+例如：
+
+```shell
+curl --user your_username:your_password_or_token \
+     --upload-file path/to/package.zip \
+     https://gitea.example.com/api/packages/testuser/cran/bin?platform=windows&rversion=4.2
+```
+
+如果同名和版本的软件包已存在，则无法发布软件包。您必须首先删除现有的软件包。
+
+## 安装软件包
+
+要从软件包注册表中安装R软件包，请执行以下命令：
+
+```shell
+install.packages("{package_name}")
+```
+
+| 参数           | 描述              |
+| -------------- | ----------------- |
+| `package_name` | The package name. |
+
+例如：
+
+```shell
+install.packages("testpackage")
+```
diff --git a/docs/document/usage/packages/debian.md b/docs/document/usage/packages/debian.md
new file mode 100644
index 0000000..4ea6480
--- /dev/null
+++ b/docs/document/usage/packages/debian.md
@@ -0,0 +1,121 @@
+---
+date: "2023-01-07T00:00:00+00:00"
+slug: "debian"
+---
+
+# Debian 软件包注册表
+
+为您的用户或组织发布 [Debian](https://www.debian.org/distrib/packages) 软件包。
+
+## 要求
+
+要使用 Debian 注册表，您需要使用类似于 `curl` 的 HTTP 客户端进行上传，并使用类似于 `apt` 的软件包管理器消费软件包。
+
+以下示例使用 `apt`。
+
+## 配置软件包注册表
+
+要注册 Debian 注册表，请将 URL 添加到已知 `apt` 源列表中：
+
+```shell
+echo "deb [signed-by=/etc/apt/keyrings/gitea-{owner}.asc] https://gitea.example.com/api/packages/{owner}/debian {distribution} {component}" | sudo tee -a /etc/apt/sources.list.d/gitea.list
+```
+
+| 占位符         | 描述           |
+| -------------- | -------------- |
+| `owner`        | 软件包的所有者 |
+| `distribution` | 要使用的发行版 |
+| `component`    | 要使用的组件   |
+
+如果注册表是私有的，请在 URL 中提供凭据。您可以使用密码或[个人访问令牌](development/api-usage.md#通过-api-认证)：
+
+```shell
+echo "deb [signed-by=/etc/apt/keyrings/gitea-{owner}.asc] https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/debian {distribution} {component}" | sudo tee -a /etc/apt/sources.list.d/gitea.list
+```
+
+Debian 注册表文件使用 PGP 密钥进行签名，`apt` 必须知道该密钥：
+
+```shell
+sudo curl https://gitea.example.com/api/packages/{owner}/debian/repository.key -o /etc/apt/keyrings/gitea-{owner}.asc
+```
+
+然后更新本地软件包索引：
+
+```shell
+apt update
+```
+
+## 发布软件包
+
+要发布一个 Debian 软件包（`*.deb`），执行 HTTP `PUT` 操作，并将软件包内容放入请求主体中。
+
+```
+PUT https://gitea.example.com/api/packages/{owner}/debian/pool/{distribution}/{component}/upload
+```
+
+| 参数           | 描述                                                  |
+| -------------- | ----------------------------------------------------- |
+| `owner`        | 软件包的所有者                                        |
+| `distribution` | 发行版，可能与操作系统的发行版名称匹配，例如 `bionic` |
+| `component`    | 组件，可用于分组软件包，或仅为 `main` 或类似的组件。  |
+
+使用 HTTP 基本身份验证的示例请求：
+
+```shell
+curl --user your_username:your_password_or_token \
+     --upload-file path/to/file.deb \
+     https://gitea.example.com/api/packages/testuser/debian/pool/bionic/main/upload
+```
+
+如果您使用 2FA 或 OAuth，请使用[个人访问令牌](development/api-usage.md#通过-api-认证)替代密码。
+您无法向软件包中多次发布具有相同名称的文件。您必须首先删除现有的软件包版本。
+
+服务器将使用以下 HTTP 状态代码进行响应。
+
+| HTTP 状态码       | 意义                                     |
+| ----------------- | ---------------------------------------- |
+| `201 Created`     | 软件包已发布                             |
+| `400 Bad Request` | 软件包名称、版本、发行版、组件或架构无效 |
+| `409 Conflict`    | 具有相同参数组合的软件包文件已经存在     |
+
+## 删除软件包
+
+要删除 Debian 软件包，请执行 HTTP `DELETE` 操作。如果没有文件留下，这将同时删除软件包版本。
+
+```
+DELETE https://gitea.example.com/api/packages/{owner}/debian/pool/{distribution}/{component}/{package_name}/{package_version}/{architecture}
+```
+
+| 参数              | 描述           |
+| ----------------- | -------------- |
+| `owner`           | 软件包的所有者 |
+| `package_name`    | 软件包名称     |
+| `package_version` | 软件包版本     |
+| `distribution`    | 软件包发行版   |
+| `component`       | 软件包组件     |
+| `architecture`    | 软件包架构     |
+
+使用 HTTP 基本身份验证的示例请求：
+
+```shell
+curl --user your_username:your_token_or_password -X DELETE \
+     https://gitea.example.com/api/packages/testuser/debian/pools/bionic/main/test-package/1.0.0/amd64
+```
+
+服务器将使用以下 HTTP 状态代码进行响应。
+
+| HTTP 状态码      | 含义               |
+| ---------------- | ------------------ |
+| `204 No Content` | 成功               |
+| `404 Not Found`  | 找不到软件包或文件 |
+
+## 安装软件包
+
+要从 Debian 注册表安装软件包，请执行以下命令:
+
+```shell
+# use latest version
+apt install {package_name}
+# use specific version
+apt install {package_name}={package_version}
+```
diff --git a/docs/document/usage/packages/generic.md b/docs/document/usage/packages/generic.md
new file mode 100644
index 0000000..4346caf
--- /dev/null
+++ b/docs/document/usage/packages/generic.md
@@ -0,0 +1,135 @@
+---
+date: "2021-07-20T00:00:00+00:00"
+slug: "generic"
+sidebar_position: 500
+---
+
+# 通用软件包注册表
+
+发布通用文件，如发布二进制文件或其他输出，供您的用户或组织使用。
+
+## 身份验证软件包注册表
+
+要身份验证软件包注册表，您需要提供[自定义 HTTP 头或使用 HTTP 基本身份验证](development/api-usage.md#通过-api-认证)。
+
+## 发布软件包
+
+要发布通用软件包，请执行 HTTP `PUT` 操作，并将软件包内容放入请求主体中。
+您无法向软件包中多次发布具有相同名称的文件。您必须首先删除现有的软件包版本。
+
+```
+PUT https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{file_name}
+```
+
+| 参数              | 描述                                                                                                                        |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `owner`           | 软件包的所有者。                                                                                                            |
+| `package_name`    | 软件包名称。它只能包含小写字母 (`a-z`)、大写字母 (`A-Z`)、数字 (`0-9`)、点号 (`.`)、连字符 (`-`)、加号 (`+`) 或下划线 (`_`) |
+| `package_version` | 软件包版本，一个非空字符串，不包含前导或尾随空格                                                                            |
+| `file_name`       | 文件名。它只能包含小写字母 (`a-z`)、大写字母 (`A-Z`)、数字 (`0-9`)、点号 (`.`)、连字符 (`-`)、加号 (`+`) 或下划线 (`_`)     |
+
+使用 HTTP 基本身份验证的示例请求：
+
+```shell
+curl --user your_username:your_password_or_token \
+     --upload-file path/to/file.bin \
+     https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin
+```
+
+如果您使用 2FA 或 OAuth，请使用[个人访问令牌](development/api-usage.md#通过-api-认证)替代密码。
+
+服务器将使用以下 HTTP 状态代码进行响应。
+
+| HTTP 状态码       | 意义                               |
+| ----------------- | ---------------------------------- |
+| `201 Created`     | 软件包已发布                       |
+| `400 Bad Request` | 软件包名称和/或版本和/或文件名无效 |
+| `409 Conflict`    | 具有相同名称的文件已存在于软件包中 |
+
+## 下载软件包
+
+要下载通用软件包，请执行 HTTP `GET` 操作。
+
+```
+GET https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{file_name}
+```
+
+| 参数              | 描述           |
+| ----------------- | -------------- |
+| `owner`           | 软件包的所有者 |
+| `package_name`    | 软件包名称     |
+| `package_version` | 软件包版本     |
+| `file_name`       | 文件名         |
+
+文件内容将在响应主体中返回。响应的内容类型为 `application/octet-stream`。
+
+服务器将使用以下 HTTP 状态代码进行响应。
+
+```shell
+curl --user your_username:your_token_or_password \
+     https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin
+```
+
+服务器会以以下 HTTP 状态码进行响应：
+
+| HTTP 状态码     | 含义                 |
+| --------------- | -------------------- |
+| `200 OK`        | 成功                 |
+| `404 Not Found` | 找不到软件包或者文件 |
+
+## 删除软件包
+
+要删除通用软件包，请执行 HTTP DELETE 操作。这将同时删除该版本的所有文件。
+
+```
+DELETE https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}
+```
+
+| 参数              | 描述           |
+| ----------------- | -------------- |
+| `owner`           | 软件包的所有者 |
+| `package_name`    | 软件包名称     |
+| `package_version` | 软件包版本     |
+
+服务器将使用以下 HTTP 状态代码进行响应。
+
+```shell
+curl --user your_username:your_token_or_password -X DELETE \
+     https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0
+```
+
+The server responds with the following HTTP Status codes.
+
+| HTTP 状态码      | 意义         |
+| ---------------- | ------------ |
+| `204 No Content` | 成功         |
+| `404 Not Found`  | 找不到软件包 |
+
+## 删除软件包文件
+
+要删除通用软件包的文件，请执行 HTTP `DELETE` 操作。如果没有文件留下，这将同时删除软件包版本。
+
+```
+DELETE https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{filename}
+```
+
+| 参数              | 描述           |
+| ----------------- | -------------- |
+| `owner`           | 软件包的所有者 |
+| `package_name`    | 软件包名称     |
+| `package_version` | 软件包版本     |
+| `filename`        | 文件名         |
+
+使用 HTTP 基本身份验证的示例请求：
+
+```shell
+curl --user your_username:your_token_or_password -X DELETE \
+     https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin
+```
+
+服务器将使用以下 HTTP 状态代码进行响应：
+
+| HTTP 状态码      | 含义               |
+| ---------------- | ------------------ |
+| `204 No Content` | 成功               |
+| `404 Not Found`  | 找不到软件包或文件 |
diff --git a/docs/document/usage/packages/go.md b/docs/document/usage/packages/go.md
new file mode 100644
index 0000000..dbd15ba
--- /dev/null
+++ b/docs/document/usage/packages/go.md
@@ -0,0 +1,64 @@
+---
+date: "2023-05-10T00:00:00+00:00"
+slug: "go"
+sidebar_position: 45
+---
+
+# Go 软件包注册表
+
+为您的用户或组织发布 Go 软件包。
+
+## 发布软件包
+
+要发布 Go 软件包，请执行 HTTP `PUT` 操作，并将软件包内容放入请求主体中。
+如果已经存在相同名称和版本的软件包，您无法发布软件包。您必须首先删除现有的软件包。
+该软件包必须遵循[文档中的结构](https://go.dev/ref/mod#zip-files)。
+
+```
+PUT https://gitea.example.com/api/packages/{owner}/go/upload
+```
+
+| 参数    | 描述           |
+| ------- | -------------- |
+| `owner` | 软件包的所有者 |
+
+要身份验证到软件包注册表，您需要提供[自定义 HTTP 头或使用 HTTP 基本身份验证](development/api-usage.md#通过-api-认证)：
+
+```shell
+curl --user your_username:your_password_or_token \
+     --upload-file path/to/file.zip \
+     https://gitea.example.com/api/packages/testuser/go/upload
+```
+
+如果您使用的是 2FA 或 OAuth，请使用[个人访问令牌](development/api-usage.md#通过-api-认证)替代密码进行身份验证。
+
+服务器将使用以下 HTTP 状态代码进行响应。
+
+| HTTP 状态码       | 含义                       |
+| ----------------- | -------------------------- |
+| `201 Created`     | 软件包已发布               |
+| `400 Bad Request` | 软件包无效                 |
+| `409 Conflict`    | 具有相同名称的软件包已存在 |
+
+## 安装软件包
+
+要安装Go软件包，请指示Go使用软件包注册表作为代理：
+
+```shell
+# 使用最新版本
+GOPROXY=https://gitea.example.com/api/packages/{owner}/go go install {package_name}
+# 或者
+GOPROXY=https://gitea.example.com/api/packages/{owner}/go go install {package_name}@latest
+# 使用特定版本
+GOPROXY=https://gitea.example.com/api/packages/{owner}/go go install {package_name}@{package_version}
+```
+
+| 参数              | 描述           |
+| ----------------- | -------------- |
+| `owner`           | 软件包的所有者 |
+| `package_name`    | 软件包名称     |
+| `package_version` | 软件包版本     |
+
+如果软件包的所有者是私有的，则需要[提供凭据](https://go.dev/ref/mod#private-module-proxy-auth)。
+
+有关 `GOPROXY` 环境变量的更多信息以及如何防止数据泄漏的信息，请[参阅文档](https://go.dev/ref/mod#private-modules)。
diff --git a/docs/document/usage/packages/helm.md b/docs/document/usage/packages/helm.md
new file mode 100644
index 0000000..d3cffa6
--- /dev/null
+++ b/docs/document/usage/packages/helm.md
@@ -0,0 +1,55 @@
+---
+date: "2022-04-14T00:00:00+00:00"
+slug: "helm"
+sidebar_position: 50
+---
+
+# Helm Chart 注册表
+
+为您的用户或组织发布 [Helm](https://helm.sh/) charts。
+
+## 要求
+
+要使用 Helm Chart 注册表，可以使用诸如 `curl` 或 [`helm cm-push`](https://github.com/chartmuseum/helm-push/) 插件之类的简单HTTP客户端。
+
+## 发布软件包
+
+通过运行以下命令来发布软件包：
+
+```shell
+curl --user {username}:{password} -X POST --upload-file ./{chart_file}.tgz https://gitea.example.com/api/packages/{owner}/helm/api/charts
+```
+
+或者使用 `helm cm-push` 插件：
+
+```shell
+helm repo add  --username {username} --password {password} {repo} https://gitea.example.com/api/packages/{owner}/helm
+helm cm-push ./{chart_file}.tgz {repo}
+```
+
+| 参数         | 描述                                                                                                                                                   |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `username`   | 您的Gitea用户名                                                                                                                                        |
+| `password`   | 您的Gitea密码。如果您使用的是2FA或OAuth，请使用[个人访问令牌](development/api-usage.md#通过-api-认证)替代密码进行身份验证。 |
+| `repo`       | 仓库名称                                                                                                                                               |
+| `chart_file` | Helm Chart 归档文件                                                                                                                                    |
+| `owner`      | 软件包的所有者                                                                                                                                         |
+
+## 安装软件包
+
+要从注册表中安装Helm Chart，请执行以下命令：
+
+```shell
+helm repo add  --username {username} --password {password} {repo} https://gitea.example.com/api/packages/{owner}/helm
+helm repo update
+helm install {name} {repo}/{chart}
+```
+
+| 参数       | 描述                        |
+| ---------- | --------------------------- |
+| `username` | 您的Gitea用户名             |
+| `password` | 您的Gitea密码或个人访问令牌 |
+| `repo`     | 存储库的名称                |
+| `owner`    | 软件包的所有者              |
+| `name`     | 本地名称                    |
+| `chart`    | Helm Chart的名称            |
diff --git a/docs/document/usage/packages/maven.md b/docs/document/usage/packages/maven.md
new file mode 100644
index 0000000..deae163
--- /dev/null
+++ b/docs/document/usage/packages/maven.md
@@ -0,0 +1,154 @@
+---
+date: "2021-07-20T00:00:00+00:00"
+slug: "maven"
+sidebar_position: 60
+---
+
+# Maven 软件包注册表
+
+为您的用户或组织发布 [Maven](https://maven.apache.org) 软件包。
+
+## 要求
+
+要使用 Maven 软件包注册表，您可以使用 [Maven](https://maven.apache.org/install.html) 或 [Gradle](https://gradle.org/install/)。
+以下示例使用 `Maven` 和 `Gradle Groovy`。
+
+## 配置软件包注册表
+
+要注册软件包注册表，首先需要将访问令牌添加到 [`settings.xml`](https://maven.apache.org/settings.html) 文件中：
+
+```xml
+<settings>
+  <servers>
+    <server>
+      <id>gitea</id>
+      <configuration>
+        <httpHeaders>
+          <property>
+            <name>Authorization</name>
+            <value>token {access_token}</value>
+          </property>
+        </httpHeaders>
+      </configuration>
+    </server>
+  </servers>
+</settings>
+```
+
+然后在项目的 `pom.xml` 文件中添加以下部分：
+
+```xml
+<repositories>
+  <repository>
+    <id>gitea</id>
+    <url>https://gitea.example.com/api/packages/{owner}/maven</url>
+  </repository>
+</repositories>
+<distributionManagement>
+  <repository>
+    <id>gitea</id>
+    <url>https://gitea.example.com/api/packages/{owner}/maven</url>
+  </repository>
+  <snapshotRepository>
+    <id>gitea</id>
+    <url>https://gitea.example.com/api/packages/{owner}/maven</url>
+  </snapshotRepository>
+</distributionManagement>
+```
+
+| 参数           | 描述                                                                                  |
+| -------------- | ------------------------------------------------------------------------------------- |
+| `access_token` | 您的[个人访问令牌](development/api-usage.md#通过-api-认证) |
+| `owner`        | 软件包的所有者                                                                        |
+
+### Gradle variant
+
+如果您计划在项目中添加来自 Gitea 实例的一些软件包，请将其添加到 repositories 部分中：
+
+```groovy
+repositories {
+    // other repositories
+    maven { url "https://gitea.example.com/api/packages/{owner}/maven" }
+}
+```
+
+在 Groovy gradle 中，您可以在发布部分中包含以下脚本：
+
+```groovy
+publishing {
+    // 其他发布设置
+    repositories {
+        maven {
+            name = "Gitea"
+            url = uri("https://gitea.example.com/api/packages/{owner}/maven")
+
+            credentials(HttpHeaderCredentials) {
+                name = "Authorization"
+                value = "token {access_token}"
+            }
+
+            authentication {
+                header(HttpHeaderAuthentication)
+            }
+        }
+    }
+}
+```
+
+## 发布软件包
+
+要发布软件包，只需运行以下命令：
+
+```shell
+mvn deploy
+```
+
+或者，如果您使用的是 Gradle，请使用 `gradle` 命令和 `publishAllPublicationsToGiteaRepository` 任务：
+
+```groovy
+./gradlew publishAllPublicationsToGiteaRepository
+```
+
+如果您想要将预构建的软件包发布到注册表中，可以使用 [`mvn deploy:deploy-file`](https://maven.apache.org/plugins/maven-deploy-plugin/deploy-file-mojo.html) 命令：
+
+```shell
+mvn deploy:deploy-file -Durl=https://gitea.example.com/api/packages/{owner}/maven -DrepositoryId=gitea -Dfile=/path/to/package.jar
+```
+
+| 参数    | 描述           |
+| ------- | -------------- |
+| `owner` | 软件包的所有者 |
+
+如果存在相同名称和版本的软件包，您无法发布该软件包。您必须先删除现有的软件包。
+
+## 安装软件包
+
+要从软件包注册表中安装 Maven 软件包，请在项目的 `pom.xml` 文件中添加新的依赖项：
+
+```xml
+<dependency>
+  <groupId>com.test.package</groupId>
+  <artifactId>test_project</artifactId>
+  <version>1.0.0</version>
+</dependency>
+```
+
+在 `Gradle Groovy` 中类似的操作如下：
+
+```groovy
+implementation "com.test.package:test_project:1.0.0"
+```
+
+然后运行：
+
+```shell
+mvn install
+```
+
+## 支持的命令
+
+```
+mvn install
+mvn deploy
+mvn dependency:get:
+```
diff --git a/docs/document/usage/packages/npm.md b/docs/document/usage/packages/npm.md
new file mode 100644
index 0000000..2d2d88d
--- /dev/null
+++ b/docs/document/usage/packages/npm.md
@@ -0,0 +1,132 @@
+---
+date: "2021-07-20T00:00:00+00:00"
+slug: "npm"
+sidebar_position: 70
+---
+
+# NPM Package Registry
+
+为您的用户或组织发布 [npm](https://www.npmjs.com/) 包。
+
+## 要求
+
+要使用 npm 包注册表，您需要安装 [Node.js](https://nodejs.org/en/download/)  以及与之配套的软件包管理器，例如 [Yarn](https://classic.yarnpkg.com/en/docs/install) 或 [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm/) 本身。
+
+该注册表支持[作用域](https://docs.npmjs.com/misc/scope/)和非作用域软件包。
+
+以下示例使用具有作用域 `@test` 的 `npm` 工具。
+
+## 配置软件包注册表
+
+要注册软件包注册表，您需要配置一个新的软件包源。
+
+```shell
+npm config set {scope}:registry=https://gitea.example.com/api/packages/{owner}/npm/
+npm config set -- '//gitea.example.com/api/packages/{owner}/npm/:_authToken' "{token}"
+```
+
+| 参数    | 描述                                                                                    |
+| ------- | --------------------------------------------------------------------------------------- |
+| `scope` | 软件包的作用域                                                                          |
+| `owner` | 软件包的所有者                                                                          |
+| `token` | 您的[个人访问令牌](development/api-usage.md#通过-api-认证)。 |
+
+例如：
+
+```shell
+npm config set @test:registry=https://gitea.example.com/api/packages/testuser/npm/
+npm config set -- '//gitea.example.com/api/packages/testuser/npm/:_authToken' "personal_access_token"
+```
+
+或者，不使用作用域：
+
+```shell
+npm config set registry https://gitea.example.com/api/packages/testuser/npm/
+npm config set -- '//gitea.example.com/api/packages/testuser/npm/:_authToken' "personal_access_token"
+```
+
+## 发布软件包
+
+在项目中运行以下命令发布软件包：
+
+```shell
+npm publish
+```
+
+如果已经存在相同名称和版本的软件包，您无法发布该软件包。您必须先删除现有的软件包。
+
+## 删除软件包
+
+通过运行以下命令删除软件包：
+
+```shell
+npm unpublish {package_name}[@{package_version}]
+```
+
+| 参数              | 描述       |
+| ----------------- | ---------- |
+| `package_name`    | 软件包名称 |
+| `package_version` | 软件包版本 |
+
+例如
+
+```shell
+npm unpublish @test/test_package
+npm unpublish @test/test_package@1.0.0
+```
+
+## 安装软件包
+
+要从软件包注册表中安装软件包，请执行以下命令：
+
+```shell
+npm install {package_name}
+```
+
+| 参数           | 描述       |
+| -------------- | ---------- |
+| `package_name` | 软件包名称 |
+
+例如：
+
+```shell
+npm install @test/test_package
+```
+
+## 给软件包打标签
+
+该注册表支持[版本标签](https://docs.npmjs.com/adding-dist-tags-to-packages/)，可以通过 `npm dist-tag` 管理：
+
+```shell
+npm dist-tag add {package_name}@{version} {tag}
+```
+
+| 参数           | 描述       |
+| -------------- | ---------- |
+| `package_name` | 软件包名称 |
+| `version`      | 软件包版本 |
+| `tag`          | 软件包标签 |
+
+例如：
+
+```shell
+npm dist-tag add test_package@1.0.2 release
+```
+
+标签名称不能是有效的版本。所有可解析为版本的标签名称都将被拒绝。
+
+## 搜索软件包
+
+该注册表支持[搜索](https://docs.npmjs.com/cli/v7/commands/npm-search/)，但不支持像 `author:gitea` 这样的特殊搜索限定符。
+
+## 支持的命令
+
+```
+npm install
+npm ci
+npm publish
+npm unpublish
+npm dist-tag
+npm view
+npm search
+```
diff --git a/docs/document/usage/packages/nuget.md b/docs/document/usage/packages/nuget.md
new file mode 100644
index 0000000..2d7ecaa
--- /dev/null
+++ b/docs/document/usage/packages/nuget.md
@@ -0,0 +1,105 @@
+---
+date: "2021-07-20T00:00:00+00:00"
+slug: "nuget"
+sidebar_position: 80
+---
+
+# NuGet 软件包注册表
+
+发布适用于您的用户或组织的 [NuGet](https://www.nuget.org/) 软件包。软件包注册表支持 V2 和 V3 API 协议，并且您还可以使用 [NuGet 符号软件包](https://docs.microsoft.com/en-us/nuget/create-packages/symbol-packages-snupkg)。
+
+## 要求
+
+要使用 NuGet 软件包注册表，您可以使用命令行界面工具，以及各种集成开发环境（IDE）中的 NuGet 功能，如 Visual Studio。有关 NuGet 客户端的更多信息，请参[阅官方文档](https://docs.microsoft.com/en-us/nuget/install-nuget-client-tools)。
+以下示例使用 `dotnet nuget` 工具。
+
+## 配置软件包注册表
+
+要注册软件包注册表，您需要配置一个新的NuGet源：
+
+```shell
+dotnet nuget add source --name {source_name} --username {username} --password {password} https://gitea.example.com/api/packages/{owner}/nuget/index.json
+```
+
+| 参数          | 描述                                                                                                                                   |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `source_name` | 所需源名称                                                                                                                             |
+| `username`    | 您的Gitea用户名                                                                                                                        |
+| `password`    | 您的Gitea密码。如果您使用2FA或OAuth，请使用[个人访问令牌](development/api-usage.md#通过-api-认证)代替密码。 |
+| `owner`       | 软件包的所有者                                                                                                                         |
+
+例如：
+
+```shell
+dotnet nuget add source --name gitea --username testuser --password password123 https://gitea.example.com/api/packages/testuser/nuget/index.json
+```
+
+您可以在不提供凭据的情况下添加源，并在发布软件包时使用--api-key参数。在这种情况下，您需要提供[个人访问令牌](development/api-usage.md#通过-api-认证)。
+
+## 发布软件包
+
+通过运行以下命令发布软件包：
+
+```shell
+dotnet nuget push --source {source_name} {package_file}
+```
+
+| 参数           | 描述                         |
+| -------------- | ---------------------------- |
+| `source_name`  | 所需源名称                   |
+| `package_file` | 软件包 `.nupkg` 文件的路径。 |
+
+例如：
+
+```shell
+dotnet nuget push --source gitea test_package.1.0.0.nupkg
+```
+
+如果已经存在相同名称和版本的软件包，您无法发布该软件包。您必须先删除现有的软件包。
+
+### 符号软件包
+
+NuGet 软件包注册表支持构建用于符号服务器的符号软件包。客户端可以请求嵌入在符号软件包（`.snupkg`）中的 PDB 文件。
+为此，请将 NuGet 软件包注册表注册为符号源：
+
+```
+https://gitea.example.com/api/packages/{owner}/nuget/symbols
+```
+
+| 参数    | 描述                 |
+| ------- | -------------------- |
+| `owner` | 软件包注册表的所有者 |
+
+例如：
+
+```
+https://gitea.example.com/api/packages/testuser/nuget/symbols
+```
+
+## 安装软件包
+
+要从软件包注册表安装 NuGet 软件包，请执行以下命令：
+
+```shell
+dotnet add package --source {source_name} --version {package_version} {package_name}
+```
+
+| 参数              | 描述         |
+| ----------------- | ------------ |
+| `source_name`     | 所需源名称   |
+| `package_name`    | 软件包名称   |
+| `package_version` | 软件包版本。 |
+
+例如：
+
+```shell
+dotnet add package --source gitea --version 1.0.0 test_package
+```
+
+## 支持的命令
+
+```
+dotnet add
+dotnet nuget push
+dotnet nuget delete
+```
diff --git a/docs/document/usage/packages/overview.md b/docs/document/usage/packages/overview.md
new file mode 100644
index 0000000..0170ab8
--- /dev/null
+++ b/docs/document/usage/packages/overview.md
@@ -0,0 +1,96 @@
+---
+date: "2021-07-20T00:00:00+00:00"
+slug: "overview"
+sidebar_position: 1
+---
+
+# 软件包注册表
+
+从Gitea **1.17**版本开始，软件包注册表可以用作常见软件包管理器的公共或私有注册表。
+
+## 支持的软件包管理器
+
+目前支持以下软件包管理器：
+
+| Name                                                                | Language   | Package client            |
+| ------------------------------------------------------------------- | ---------- | ------------------------- |
+| [Alpine](usage/packages/alpine.md)       | -          | `apk`                     |
+| [Cargo](usage/packages/cargo.md)         | Rust       | `cargo`                   |
+| [Chef](usage/packages/chef.md)           | -          | `knife`                   |
+| [Composer](usage/packages/composer.md)   | PHP        | `composer`                |
+| [Conan](usage/packages/conan.md)         | C++        | `conan`                   |
+| [Conda](usage/packages/conda.md)         | -          | `conda`                   |
+| [Container](usage/packages/container.md) | -          | 任何符合OCI规范的客户端   |
+| [CRAN](usage/packages/cran.md)           | R          | -                         |
+| [Debian](usage/packages/debian.md)       | -          | `apt`                     |
+| [Generic](usage/packages/generic.md)     | -          | 任何HTTP客户端            |
+| [Go](usage/packages/go.md)               | Go         | `go`                      |
+| [Helm](usage/packages/helm.md)           | -          | 任何HTTP客户端, `cm-push` |
+| [Maven](usage/packages/maven.md)         | Java       | `mvn`, `gradle`           |
+| [npm](usage/packages/npm.md)             | JavaScript | `npm`, `yarn`, `pnpm`     |
+| [NuGet](usage/packages/nuget.md)         | .NET       | `nuget`                   |
+| [Pub](usage/packages/pub.md)             | Dart       | `dart`, `flutter`         |
+| [PyPI](usage/packages/pypi.md)           | Python     | `pip`, `twine`            |
+| [RPM](usage/packages/rpm.md)             | -          | `yum`, `dnf`, `zypper`    |
+| [RubyGems](usage/packages/rubygems.md)   | Ruby       | `gem`, `Bundler`          |
+| [Swift](usage/packages/rubygems.md)      | Swift      | `swift`                   |
+| [Vagrant](usage/packages/vagrant.md)     | -          | `vagrant`                 |
+
+**以下段落仅适用于未全局禁用软件包的情况！**
+
+## 仓库 x 软件包
+
+软件包始终属于所有者（用户或组织），而不是仓库。
+要将（已上传的）软件包链接到仓库，请打开该软件包的设置页面，并选择要将此软件包链接到的仓库。
+将链接到整个软件包，而不仅是单个版本。
+
+链接软件包将导致在仓库的软件包列表中显示该软件包，并在软件包页面上显示到仓库的链接（以及到仓库工单的链接）。
+
+## 访问限制
+
+| 软件包所有者类型 | 用户                                     | 组织                                       |
+| ---------------- | ---------------------------------------- | ------------------------------------------ |
+| **读取** 访问    | 公开，如果用户也是公开的；否则仅限此用户 | 公开，如果组织是公开的，否则仅限组织成员   |
+| **写入** 访问    | 仅软件包所有者                           | 具有组织中的管理员或写入访问权限的组织成员 |
+
+注意：这些访问限制可能会[变化](https://github.com/go-gitea/gitea/issues/19270)，将通过专门的组织团队权限添加更细粒度的控制。
+
+## 创建或上传软件包
+
+根据软件包类型，使用相应的软件包管理器。请查看特定软件包管理器的子页面以获取说明。
+
+## 查看软件包
+
+您可以在仓库页面上查看仓库的软件包。
+
+1. 转到仓库主页。
+2. 在导航栏中选择**软件包**
+
+要查看有关软件包的更多详细信息，请选择软件包的名称。
+
+## 下载软件包
+
+要从仓库下载软件包：
+
+1. 在导航栏中选择**软件包**
+2. 选择软件包的名称以查看详细信息。
+3. 在 **Assets** 部分，选择要下载的软件包文件的名称。
+
+## 删除软件包
+
+在将软件包发布到软件包注册表后，您无法编辑软件包。相反，您必须删除并重新创建它。
+
+要从仓库中删除软件包：
+
+1. 在导航栏中选择**软件包**
+2. 选择软件包的名称以查看详细信息。
+3. 单击**删除软件包**以永久删除软件包。
+
+## 禁用软件包注册表
+
+包注册表已自动启用。要在单个存储库中禁用它：
+
+1. 在导航栏中选择**设置**。
+2. 禁用**启用仓库软件包注册表**.
+
+禁用软件包注册表不会删除先前发布的软件包。
diff --git a/docs/document/usage/packages/pub.md b/docs/document/usage/packages/pub.md
new file mode 100644
index 0000000..2586233
--- /dev/null
+++ b/docs/document/usage/packages/pub.md
@@ -0,0 +1,71 @@
+---
+date: "2022-07-31T00:00:00+00:00"
+slug: "pub"
+sidebar_position: 90
+---
+
+# Pub 软件包注册表
+
+为您的用户或组织发布 [Pub](https://dart.dev/guides/packages) 软件包。
+
+## 要求
+
+要使用Pub软件包注册表，您需要使用 [dart](https://dart.dev/tools/dart-tool) 和/或 [flutter](https://docs.flutter.dev/reference/flutter-cli). 工具。
+
+以下示例使用 `dart`。
+
+## 配置软件包注册表
+
+要注册软件包注册表并提供凭据，请执行以下操作：
+
+```shell
+dart pub token add https://gitea.example.com/api/packages/{owner}/pub
+```
+
+| 占位符  | 描述           |
+| ------- | -------------- |
+| `owner` | 软件包的所有者 |
+
+您需要提供您的[个人访问令牌](development/api-usage.md#通过-api-认证)。
+
+## 发布软件包
+
+要发布软件包，请编辑 `pubspec.yaml` 文件，并添加以下行：
+
+```yaml
+publish_to: https://gitea.example.com/api/packages/{owner}/pub
+```
+
+| 占位符  | 描述           |
+| ------- | -------------- |
+| `owner` | 软件包的所有者 |
+
+现在，您可以通过运行以下命令来发布软件包：
+
+```shell
+dart pub publish
+```
+
+如果已存在具有相同名称和版本的软件包，则无法发布软件包。您必须先删除现有的软件包。
+
+## 安装软件包
+
+要从软件包注册表安装Pub软件包，请执行以下命令：
+
+```shell
+dart pub add {package_name} --hosted-url=https://gitea.example.com/api/packages/{owner}/pub/
+```
+
+| 参数           | 描述           |
+| -------------- | -------------- |
+| `owner`        | 软件包的所有者 |
+| `package_name` | 软件包名称     |
+
+例如：
+
+```shell
+# use latest version
+dart pub add mypackage --hosted-url=https://gitea.example.com/api/packages/testuser/pub/
+# specify version
+dart pub add mypackage:1.0.8 --hosted-url=https://gitea.example.com/api/packages/testuser/pub/
+```
diff --git a/docs/document/usage/packages/pypi.md b/docs/document/usage/packages/pypi.md
new file mode 100644
index 0000000..ccfd228
--- /dev/null
+++ b/docs/document/usage/packages/pypi.md
@@ -0,0 +1,75 @@
+---
+date: "2021-07-20T00:00:00+00:00"
+slug: "pypi"
+sidebar_position: 100
+---
+
+# PyPI 软件包注册表
+
+为您的用户或组织发布 [PyPI](https://pypi.org/) 软件包。
+
+## 要求
+
+要使用 PyPI 软件包注册表，您需要使用 [pip](https://pypi.org/project/pip/) 工具来消费和使用 [twine](https://pypi.org/project/twine/) 工具来发布软件包。
+
+## 配置软件包注册表
+
+要注册软件包注册表，您需要编辑本地的 `~/.pypirc` 文件。添加以下内容：
+
+```ini
+[distutils]
+index-servers = gitea
+
+[gitea]
+repository = https://gitea.example.com/api/packages/{owner}/pypi
+username = {username}
+password = {password}
+```
+
+| 占位符     | 描述                                                                                                                                      |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `owner`    | 软件包的所有者                                                                                                                            |
+| `username` | 您的 Gitea 用户名                                                                                                                         |
+| `password` | 您的 Gitea 密码。如果您使用 2FA 或 OAuth，请使用[个人访问令牌](development/api-usage.md#通过-api-认证)替代密码 |
+
+## 发布软件包
+
+通过运行以下命令来发布软件包：
+
+```shell
+python3 -m twine upload --repository gitea /path/to/files/*
+```
+
+软件包文件的扩展名为 `.tar.gz` 和 `.whl`。
+
+如果已存在具有相同名称和版本的软件包，则无法发布软件包。您必须先删除现有的软件包。
+
+## 安装软件包
+
+要从软件包注册表安装 PyPI 软件包，请执行以下命令：
+
+```shell
+pip install --index-url https://{username}:{password}@gitea.example.com/api/packages/{owner}/pypi/simple --no-deps {package_name}
+```
+
+| 参数           | 描述                          |
+| -------------- | ----------------------------- |
+| `username`     | 您的 Gitea 用户名             |
+| `password`     | 您的 Gitea 密码或个人访问令牌 |
+| `owner`        | 软件包的所有者                |
+| `package_name` | 软件包名称                    |
+
+例如：
+
+```shell
+pip install --index-url https://testuser:password123@gitea.example.com/api/packages/testuser/pypi/simple --no-deps test_package
+```
+
+您可以使用 `--extra-index-url` 替代 `--index-url`，但这样会使您容易受到依赖混淆攻击，因为 `pip` 会先检查官方 PyPi 仓库中的软件包，然后再检查指定的自定义仓库。请阅读 `pip` 文档以获取更多信息。
+
+## 支持的命令
+
+```
+pip install
+twine upload
+```
diff --git a/docs/document/usage/packages/rpm.md b/docs/document/usage/packages/rpm.md
new file mode 100644
index 0000000..6cb238e
--- /dev/null
+++ b/docs/document/usage/packages/rpm.md
@@ -0,0 +1,108 @@
+---
+date: "2023-03-08T00:00:00+00:00"
+slug: "packages/rpm"
+sidebar_position: 105
+---
+
+# RPM 软件包注册表
+
+为您的用户或组织发布 [RPM](https://rpm.org/) 软件包。
+
+## 要求
+
+要使用RPM注册表，您需要使用像 `yum`, `dnf` 或 `zypper` 这样的软件包管理器来消费软件包。
+
+以下示例使用 `dnf`。
+
+## 配置软件包注册表
+
+要注册RPM注册表，请将 URL 添加到已知 `apt` 源列表中：
+
+```shell
+dnf config-manager --add-repo https://gitea.example.com/api/packages/{owner}/rpm/{group}.repo
+```
+
+| 占位符  | 描述                                   |
+| ------- |--------------------------------------|
+| `owner` | 软件包的所有者                           |
+| `group` | 任何名称,例如 `centos/7`、`el-7`、`fc38` |
+
+如果注册表是私有的，请在URL中提供凭据。您可以使用密码或[个人访问令牌](development/api-usage.md#通过-api-认证)：
+
+```shell
+dnf config-manager --add-repo https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/rpm/{group}.repo
+```
+
+您还必须将凭据添加到 `/etc/yum.repos.d` 中的 `rpm.repo` 文件中的URL中。
+
+## 发布软件包
+
+要发布RPM软件包（`*.rpm`），请执行带有软件包内容的 HTTP `PUT` 操作。
+
+```
+PUT https://gitea.example.com/api/packages/{owner}/rpm/{group}/upload
+```
+
+| 参数    | 描述           |
+| ------- |--------------|
+| `owner` | 软件包的所有者      |
+| `group` | 软件包自定义分组名称 |
+
+使用HTTP基本身份验证的示例请求：
+
+```shell
+curl --user your_username:your_password_or_token \
+     --upload-file path/to/file.rpm \
+     https://gitea.example.com/api/packages/testuser/rpm/centos/el7/version/upload
+```
+
+如果您使用 2FA 或 OAuth，请使用[个人访问令牌](development/api-usage.md#通过-api-认证)替代密码。您无法将具有相同名称的文件两次发布到软件包中。您必须先删除现有的软件包版本。
+
+服务器将以以下HTTP状态码响应。
+
+| HTTP 状态码       | 含义                                             |
+| ----------------- | ------------------------------------------------ |
+| `201 Created`     | 软件包已发布                                     |
+| `400 Bad Request` | 软件包无效                                       |
+| `409 Conflict`    | 具有相同参数组合的软件包文件已经存在于该软件包中 |
+
+## 删除软件包
+
+要删除 RPM 软件包，请执行 HTTP `DELETE` 操作。如果没有文件剩余，这也将删除软件包版本。
+
+```
+DELETE https://gitea.example.com/api/packages/{owner}/rpm/{group}/package/{package_name}/{package_version}/{architecture}
+```
+
+| 参数              | 描述           |
+| ----------------- | -------------- |
+| `owner`           | 软件包的所有者 |
+| `group`         | 软件包自定义分组 |
+| `package_name`    | 软件包名称     |
+| `package_version` | 软件包版本     |
+| `architecture`    | 软件包架构     |
+
+使用HTTP基本身份验证的示例请求：
+
+```shell
+curl --user your_username:your_token_or_password -X DELETE \
+     https://gitea.example.com/api/packages/testuser/rpm/centos/el7/package/test-package/1.0.0/x86_64
+```
+
+服务器将以以下HTTP状态码响应：
+
+| HTTP 状态码      | 含义               |
+| ---------------- | ------------------ |
+| `204 No Content` | 成功               |
+| `404 Not Found`  | 未找到软件包或文件 |
+
+## 安装软件包
+
+要从RPM注册表安装软件包，请执行以下命令：
+
+```shell
+# use latest version
+dnf install {package_name}
+# use specific version
+dnf install {package_name}-{package_version}.{architecture}
+```
diff --git a/docs/document/usage/packages/rubygems.md b/docs/document/usage/packages/rubygems.md
new file mode 100644
index 0000000..96cd500
--- /dev/null
+++ b/docs/document/usage/packages/rubygems.md
@@ -0,0 +1,115 @@
+---
+date: "2021-07-20T00:00:00+00:00"
+slug: "rubygems"
+sidebar_position: 110
+---
+
+# RubyGems 软件包注册表
+
+为您的用户或组织发布 [RubyGems](https://guides.rubygems.org/) 软件包。
+
+## 要求
+
+要使用RubyGems软件包注册表，您需要使用 [gem](https://guides.rubygems.org/command-reference/) 命令行工具来消费和发布软件包。
+
+## 配置软件包注册表
+
+要注册软件包注册表，请编辑 `~/.gem/credentials` 文件并添加：
+
+```ini
+---
+https://gitea.example.com/api/packages/{owner}/rubygems: Bearer {token}
+```
+
+| 参数    | 描述                                                                                  |
+| ------- | ------------------------------------------------------------------------------------- |
+| `owner` | 软件包的所有者                                                                        |
+| `token` | 您的[个人访问令牌](development/api-usage.md#通过-api-认证) |
+
+例如：
+
+```
+---
+https://gitea.example.com/api/packages/testuser/rubygems: Bearer 3bd626f84b01cd26b873931eace1e430a5773cc4
+```
+
+## 发布软件包
+
+通过运行以下命令来发布软件包：
+
+```shell
+gem push --host {host} {package_file}
+```
+
+| 参数           | 描述                     |
+| -------------- | ------------------------ |
+| `host`         | 软件包注册表的URL        |
+| `package_file` | 软件包 `.gem` 文件的路径 |
+
+例如：
+
+```shell
+gem push --host https://gitea.example.com/api/packages/testuser/rubygems test_package-1.0.0.gem
+```
+
+如果已经存在相同名称和版本的软件包，您将无法发布软件包。您必须先删除现有的软件包。
+
+## 安装软件包
+
+要从软件包注册表安装软件包，您可以使用 [Bundler](https://bundler.io) 或 `gem`。
+
+### Bundler
+
+在您的 `Gemfile` 中添加一个新的 `source` 块：
+
+```
+source "https://gitea.example.com/api/packages/{owner}/rubygems" do
+  gem "{package_name}"
+end
+```
+
+| 参数           | 描述           |
+| -------------- | -------------- |
+| `owner`        | 软件包的所有者 |
+| `package_name` | 软件包名称     |
+
+例如：
+
+```
+source "https://gitea.example.com/api/packages/testuser/rubygems" do
+  gem "test_package"
+end
+```
+
+之后运行以下命令：
+
+```shell
+bundle install
+```
+
+### gem
+
+执行以下命令：
+
+```shell
+gem install --host https://gitea.example.com/api/packages/{owner}/rubygems {package_name}
+```
+
+| 参数           | 描述           |
+| -------------- | -------------- |
+| `owner`        | 软件包的所有者 |
+| `package_name` | 软件包名称     |
+
+例如：
+
+```shell
+gem install --host https://gitea.example.com/api/packages/testuser/rubygems test_package
+```
+
+## 支持的命令
+
+```
+gem install
+bundle install
+gem push
+```
diff --git a/docs/document/usage/packages/storage.md b/docs/document/usage/packages/storage.md
new file mode 100644
index 0000000..bad7e97
--- /dev/null
+++ b/docs/document/usage/packages/storage.md
@@ -0,0 +1,72 @@
+---
+date: "2022-11-01T00:00:00+00:00"
+slug: "storage"
+sidebar_position: 5
+---
+
+# 存储
+
+本文档描述了软件包注册表的存储方式以及如何管理存储。
+
+## 去重
+
+软件包注册表具有内置的去重功能，可以对上传的 Blob 进行去重处理。
+如果上传了两个相同的文件，只会在文件系统上保存一个 Blob。
+这样可以确保不会浪费空间用于重复的文件。
+
+如果上传了两个具有相同文件的软件包，这两个软件包将显示相同的大小，但在文件系统上，它们只需要一半的大小。
+每当删除一个软件包时，只会删除对底层 Blob 的引用。
+此时，Blob 不会被删除，因此它们仍然占用文件系统上的空间。
+当上传新的软件包时，现有的 Blob 可能会再次被引用。
+
+这些无引用的 Blob 会在一个清理任务中被删除。
+配置设置 `OLDER_THAN` 可以配置无引用的 Blob 在被删除之前保留的时间。
+
+## 清理规则
+
+软件包注册表可能会随着时间的推移而变得很大，如果不进行清理的话。
+建议删除不必要的软件包并设置清理规则以自动管理软件包注册表的使用情况。
+每个软件包所有者（用户或组织）都可以管理应用于其软件包的清理规则。
+
+| 设置                         | 描述                                                                                                                                     |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| 启用                         | 打开或关闭清理规则。                                                                                                                     |
+| 类型                         | 每个规则管理特定的软件包类型。                                                                                                           |
+| 将模式应用于完整的软件包名称 | 如果启用，则应用以下模式到完整的软件包名称（`package/version`），否则只使用版本号（`version`）。                                         |
+| 保留最近的版本数             | 对于每个软件包要始终保留的版本数量。                                                                                                     |
+| 保留与以下模式匹配的版本     | 确定要保留哪些版本的正则表达式模式。空模式表示不保留任何版本，而 `.+` 表示保留所有版本。即使未配置，容器注册表也始终保留 `latest` 版本。 |
+| 删除早于多少天的版本         | 仅删除早于所选天数的版本。                                                                                                               |
+| 删除与以下模式匹配的版本     | 确定要删除哪些版本的正则表达式模式。空模式或 `.+` 表示如果没有其他设置指定，则删除所有软件包。                                           |
+
+每个清理规则都可以显示受影响的软件包的预览。
+这可以用来检查清理规则是否正确配置。
+
+### 正则表达式示例
+
+正则表达式模式会自动使用 `\A` 和 `\z` 锚点进行包围。
+不要在正则表达式模式中包含任何 `\A`、`\z`、`^` 或 `$` 标记，因为它们不是必要的。
+模式是不区分大小写的，与 Gitea 中的软件包注册表的行为相匹配。
+
+| Pattern                      | Description                                                                                                   |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `.*`                         | 匹配任何可能的版本。                                                                                          |
+| `v.+`                        | 匹配以 `v` 开头的版本。                                                                                       |
+| `release`                    | 仅匹配版本号为 `release`。                                                                                    |
+| `release.*`                  | 匹配以 `release` 命名或以 `release` 开头的版本。                                                              |
+| `.+-temp-.+`                 | 匹配包含 `-temp-` 的版本。                                                                                    |
+| `v.+\|release`               | 匹配以 `v` 开头的版本或版本号为 `release`。                                                                   |
+| `package/v.+\|other/release` | 匹配以 `v` 开头的 package 的版本或 `other` 的版本号为 `release`。需要启用*将模式应用于完整的软件包名称*设置。 |
+
+### 清理规则的工作原理
+
+清理规则是清理任务的一部分，定期运行。
+
+清理规则：
+
+1. 收集所有属于所有者注册表的特定软件包类型的软件包。
+2. 对于每个软件包，收集所有版本。
+3. 根据 *保留最近的版本数* 的值，从列表中排除版本。
+4. 根据 *保留与以下模式匹配的版本* 的值，从列表中排除任何版本。
+5. 根据 *删除早于多少天的版本* 的值，从列表中排除比这个值更近的版本。
+6. 根据 *删除与以下模式匹配的版本* 的值，从列表中排除任何不匹配的版本。
+7. 删除剩余的版本。
diff --git a/docs/document/usage/packages/swift.md b/docs/document/usage/packages/swift.md
new file mode 100644
index 0000000..06ffb8d
--- /dev/null
+++ b/docs/document/usage/packages/swift.md
@@ -0,0 +1,81 @@
+---
+date: "2023-01-10T00:00:00+00:00"
+slug: "swift"
+sidebar_position: 115
+---
+
+# Swift 软件包注册表
+
+为您的用户或组织发布 [Swift](https://www.swift.org/) 软件包。
+
+## 要求
+
+要使用 Swift 软件包注册表，您需要使用 [swift](https://www.swift.org/getting-started/) 消费软件包，并使用 HTTP 客户端（如 `curl`）发布软件包。
+
+## 配置软件包注册表
+
+要注册软件包注册表并提供凭据，请执行以下命令：
+
+```shell
+swift package-registry set https://gitea.example.com/api/packages/{owner}/swift -login {username} -password {password}
+```
+
+| 占位符     | 描述                                                                                                                                           |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `owner`    | 软件包的所有者。                                                                                                                               |
+| `username` | 您的 Gitea 用户名。                                                                                                                            |
+| `password` | 您的 Gitea 密码。如果您使用两步验证或 OAuth，请使用[个人访问令牌](development/api-usage.md#通过-api-认证)代替密码。 |
+
+登录是可选的，只有在软件包注册表是私有的情况下才需要。
+
+## 发布软件包
+
+首先，您需要打包软件包的内容：
+
+```shell
+swift package archive-source
+```
+
+要发布软件包，请执行一个带有软件包内容的 HTTP `PUT` 请求，将内容放在请求正文中。
+
+```shell --user your_username:your_password_or_token \
+curl -X PUT --user {username}:{password} \
+	 -H "Accept: application/vnd.swift.registry.v1+json" \
+	 -F source-archive=@/path/to/package.zip \
+	 -F metadata={metadata} \
+	 https://gitea.example.com/api/packages/{owner}/swift/{scope}/{name}/{version}
+```
+
+| 占位符     | 描述                                                                                                                                           |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `username` | 您的 Gitea 用户名。                                                                                                                            |
+| `password` | 您的 Gitea 密码。如果您使用两步验证或 OAuth，请使用[个人访问令牌](development/api-usage.md#通过-api-认证)代替密码。 |
+| `owner`    | 软件包的所有者。                                                                                                                               |
+| `scope`    | 软件包的作用域。                                                                                                                               |
+| `name`     | 软件包的名称。                                                                                                                                 |
+| `version`  | 软件包的版本。                                                                                                                                 |
+| `metadata` | （可选）软件包的元数据。以 JSON 编码的子集，格式参考 https://schema.org/SoftwareSourceCode                                                     |
+
+如果已经存在相同名称和版本的软件包，则无法发布软件包。您必须首先删除现有的软件包。
+
+## 安装软件包
+
+要从软件包注册表安装 Swift 软件包，请将其添加到 `Package.swift` 文件的依赖项列表中：
+
+```
+dependencies: [
+	.package(id: "{scope}.{name}", from:"{version}")
+]
+```
+
+| 参数      | 描述           |
+| --------- | -------------- |
+| `scope`   | 软件包的作用域 |
+| `name`    | 软件包的名称   |
+| `version` | 软件包的版本   |
+
+之后，执行以下命令来安装它：
+
+```shell
+swift package resolve
+```
diff --git a/docs/document/usage/packages/vagrant.md b/docs/document/usage/packages/vagrant.md
new file mode 100644
index 0000000..4f14e14
--- /dev/null
+++ b/docs/document/usage/packages/vagrant.md
@@ -0,0 +1,66 @@
+---
+date: "2022-08-23T00:00:00+00:00"
+slug: "vagrant"
+sidebar_position: 120
+---
+
+# Vagrant 软件包注册表
+
+为您的用户或组织发布 [Vagrant](https://www.vagrantup.com/) 软件包。
+
+## 要求
+
+要使用 Vagrant 软件包注册表，您需要安装 [Vagrant](https://www.vagrantup.com/downloads) 并使用类似于 `curl` 的工具进行 HTTP 请求。
+
+## 发布软件包
+
+通过执行 HTTP PUT 请求将 Vagrant box 发布到注册表：
+
+```
+PUT https://gitea.example.com/api/packages/{owner}/vagrant/{package_name}/{package_version}/{provider}.box
+```
+
+| 参数              | 描述                                                               |
+| ----------------- | ------------------------------------------------------------------ |
+| `owner`           | 软件包的所有者                                                     |
+| `package_name`    | 软件包的名称                                                       |
+| `package_version` | 软件包的版本，兼容 semver 格式                                     |
+| `provider`        | [支持的提供程序名称](https://www.vagrantup.com/docs/providers)之一 |
+
+上传 Hyper-V box 的示例：
+
+```shell
+curl --user your_username:your_password_or_token \
+     --upload-file path/to/your/vagrant.box \
+     https://gitea.example.com/api/packages/testuser/vagrant/test_system/1.0.0/hyperv.box
+```
+
+如果已经存在相同名称、版本和提供程序的软件包，则无法发布软件包。您必须首先删除现有的软件包。
+
+## 安装软件包
+
+要从软件包注册表安装软件包，请执行以下命令：
+
+```shell
+vagrant box add "https://gitea.example.com/api/packages/{owner}/vagrant/{package_name}"
+```
+
+| 参数           | 描述            |
+| -------------- | --------------- |
+| `owner`        | 软件包的所有者. |
+| `package_name` | 软件包的名称    |
+
+例如：
+
+```shell
+vagrant box add "https://gitea.example.com/api/packages/testuser/vagrant/test_system"
+```
+
+这将安装软件包的最新版本。要添加特定版本，请使用` --box-version` 参数。
+如果注册表是私有的，您可以将您的[个人访问令牌](development/api-usage.md#通过-api-认证)传递给 `VAGRANT_CLOUD_TOKEN` 环境变量。
+
+## 支持的命令
+
+```
+vagrant box add
+```
diff --git a/docs/document/usage/permissions.md b/docs/document/usage/permissions.md
new file mode 100644
index 0000000..bbe0088
--- /dev/null
+++ b/docs/document/usage/permissions.md
@@ -0,0 +1,77 @@
+---
+date: "2023-05-23T09:00:00+08:00"
+slug: "permissions"
+sidebar_position: 14
+aliases:
+  - /zh-cn/permissions
+---
+
+# 权限
+
+Gitea 支持对仓库进行权限管理，这样您就可以为不同的人员提供不同的访问权限。首先，我们需要了解 `单元（Unit）`。
+
+## 单元（Unit）
+
+在 Gitea 中，我们将仓库的子模块称为 `单元（Unit）`。现在我们有以下几个单元。
+
+| 名称           | 描述                               | 权限      |
+| -------------- | ---------------------------------- | --------- |
+| 代码           | 访问源代码、文件、提交和分支。     | 读取 写入 |
+| 工单           | 组织缺陷报告、任务和里程碑。       | 读取 写入 |
+| 合并请求       | 启用合并请求和代码审核。           | 读取 写入 |
+| 发布           | 跟踪项目版本和下载。               | 读取 写入 |
+| 百科           | 与协作者编写和共享文档。           | 读取 写入 |
+| 外部百科       | 链接到外部维基。                   | 读取      |
+| 外部工单跟踪器 | 链接到外部工单跟踪器。             | 读取      |
+| 项目           | 模板仓库的 URL。                   | 读取 写入 |
+| 包             | 链接到仓库                         | 读取 写入 |
+| Actions        | 审查 Actions 日志或重启/取消工作流 | 读取 写入 |
+| 设置           | 管理仓库。                         | 管理员    |
+
+通过不同的权限，用户可以在这些单元上执行不同的操作。
+
+| 名称           | 读取                             | 写入                           | 管理员   |
+| -------------- | -------------------------------- | ------------------------------ | -------- |
+| 代码           | 查看代码树、文件、提交、分支等。 | 推送代码。                     | -        |
+| 工单           | 查看工单并创建新工单。           | 添加标签、分配、关闭工单。     | -        |
+| 合并请求       | 查看合并请求并创建新合并请求。   | 添加标签、分配、关闭合并请求。 | -        |
+| 发布           | 查看发布和下载文件。             | 创建/编辑发布。                | -        |
+| 百科           | 查看百科页面。克隆百科仓库。     | 创建/编辑百科页面，推送更改。  | -        |
+| 外部百科       | 链接到外部百科。                 | -                              | -        |
+| 外部工单跟踪器 | 链接到外部工单跟踪器。           | -                              | -        |
+| 项目           | 查看面板。                       | 在面板之间移动工单。           | -        |
+| 包             | 查看包                           | 上传/删除包                    | -        |
+| Actions        | 查看 Actions 日志                | 同意 / 取消 / 重启             | -        |
+| 设置           | -                                | -                              | 管理仓库 |
+
+个人仓库和组织仓库之间的权限存在一些差异。
+
+## 个人仓库
+
+对于个人仓库，创建者是仓库的唯一所有者，对于该仓库的任何更改或删除没有限制。
+仓库所有者可以添加协作者来帮助维护仓库。协作者可以拥有 `读取（Read）`、`写入（Write）` 和 `管理员（Admin）` 权限。
+
+访问私有仓库的体验与访问匿名公共仓库类似。您可以访问仓库中的所有可用内容，包括克隆代码、创建工单、回复工单评论、提交拉取请求等。如果你有 "写"权限，只要分支保护规则允许，你就可以向仓库的特定分支推送代码。此外，你还可以修改百科页面。有了 "管理"权限，你就可以修改仓库的设置。
+
+但如果你不是该仓库的所有者，就不能删除或转移该仓库。
+
+## 组织仓库
+
+对于个人仓库，所有者是创建它的用户。而对于组织仓库，所有者是该组织中的所有者团队成员。对该组织仓库的所有权限都取决于团队权限设置。
+
+### 所有者团队
+
+创建组织时将自动创建所有者团队，创建者将成为所有者团队的第一名成员。所有者团队不可删除，且至少有一名成员。
+
+### 管理员团队
+
+创建团队时，有两种类型的团队。一种是管理员团队，另一种是普通团队。可以创建一个管理员团队来管理某些版本库，其成员可以对这些版本库做任何事情。只有所有者或管理员团队的成员才能创建新团队。
+
+### 普通团队
+
+组织中的普通团队具有可以根据`单元(Unit)`进行权限设置。它可以有成员和存储库范围。
+
+- 一个团队可以访问所属组织的所有仓库或特殊仓库。
+- 也可以设置该团队是否有创建新仓库的权限。
+
+可以通过创建 "普通团队"，并通过权限控制对其行为进行限制。一名成员可以加入多个团队。
diff --git a/docs/document/usage/profile-readme.md b/docs/document/usage/profile-readme.md
new file mode 100644
index 0000000..5abf418
--- /dev/null
+++ b/docs/document/usage/profile-readme.md
@@ -0,0 +1,15 @@
+---
+date: "2023-05-23T09:00:00+08:00"
+slug: "profile-readme"
+sidebar_position: 12
+---
+
+# 个人资料 README
+
+要在您的 Gitea 个人资料页面显示一个 Markdown 文件，只需创建一个名为 `.profile` 的仓库，并编辑其中的 `README.md` 文件。Gitea 将自动获取该文件并在您的仓库上方显示。
+
+注意：您可以将此仓库设为私有。这样可以隐藏您的源文件，使其对公众不可见，并允许您将某些文件设为私有。但是，README.md 文件将是您个人资料上唯一存在的文件。如果您希望完全私有化 .profile 仓库，则需删除或重命名 README.md 文件。
+
+用户示例 `.profile/README.md`:
+
+![个人资料自述文件截图](../../static//images/usage/profile-readme.png)
diff --git a/docs/document/usage/protected-tags.md b/docs/document/usage/protected-tags.md
new file mode 100644
index 0000000..1bc4b8a
--- /dev/null
+++ b/docs/document/usage/protected-tags.md
@@ -0,0 +1,46 @@
+---
+date: "2023-05-23T09:00:00+08:00"
+slug: "protected-tags"
+sidebar_position: 45
+aliases:
+  - /zh-cn/protected-tags
+---
+
+# 受保护的标签
+
+受保护的标签允许控制谁有权限创建或更新 Git 标签。每个规则可以匹配单个标签名称，或者使用适当的模式来同时控制多个标签。
+
+## 设置受保护的标签
+
+要保护一个标签，你需要按照以下步骤进行操作：
+
+1. 进入仓库的**设置** > **标签**页面。
+2. 输入一个用于匹配名称的模式。你可以使用单个名称、[glob 模式](https://pkg.go.dev/github.com/gobwas/glob#Compile) 或正则表达式。
+3. 选择允许的用户和/或团队。如果将这些字段留空，则不允许任何人创建或修改此标签。
+4. 选择**保存**以保存配置。
+
+## 模式受保护的标签
+
+该模式使用 [glob](https://pkg.go.dev/github.com/gobwas/glob#Compile) 或正则表达式来匹配标签名称。对于正则表达式，你需要将模式括在斜杠中。
+
+示例：
+
+| 类型  | 模式受保护的标签         | 可能匹配的标签                          |
+| ----- | ------------------------ | --------------------------------------- |
+| Glob  | `v*`                     | `v`，`v-1`，`version2`                  |
+| Glob  | `v[0-9]`                 | `v0`，`v1` 到 `v9`                      |
+| Glob  | `*-release`              | `2.1-release`，`final-release`          |
+| Glob  | `gitea`                  | 仅限 `gitea`                            |
+| Glob  | `*gitea*`                | `gitea`，`2.1-gitea`，`1_gitea-release` |
+| Glob  | `{v,rel}-*`              | `v-`，`v-1`，`v-final`，`rel-`，`rel-x` |
+| Glob  | `*`                      | 匹配所有可能的标签名称                  |
+| Regex | `/\Av/`                  | `v`，`v-1`，`version2`                  |
+| Regex | `/\Av[0-9]\z/`           | `v0`，`v1` 到 `v9`                      |
+| Regex | `/\Av\d+\.\d+\.\d+\z/`   | `v1.0.17`，`v2.1.0`                     |
+| Regex | `/\Av\d+(\.\d+){0,2}\z/` | `v1`，`v2.1`，`v1.2.34`                 |
+| Regex | `/-release\z/`           | `2.1-release`，`final-release`          |
+| Regex | `/gitea/`                | `gitea`，`2.1-gitea`，`1_gitea-release` |
+| Regex | `/\Agitea\z/`            | 仅限 `gitea`                            |
+| Regex | `/^gitea$/`              | 仅限 `gitea`                            |
+| Regex | `/\A(v\|rel)-/`          | `v-`，`v-1`，`v-final`，`rel-`，`rel-x` |
+| Regex | `/.+/`                   | 匹配所有可能的标签名称                  |
diff --git a/docs/document/usage/pull-request.md b/docs/document/usage/pull-request.md
new file mode 100644
index 0000000..01b7a7d
--- /dev/null
+++ b/docs/document/usage/pull-request.md
@@ -0,0 +1,60 @@
+---
+date: "2018-06-01T19:00:00+02:00"
+slug: "pull-request"
+sidebar_position: 13
+aliases:
+  - /zh-cn/pull-request
+---
+
+# 合并请求
+
+合并请求(PR)是一种提出对仓库进行更改的方式。
+它是一种将一个分支合并到另一个分支的请求，附带有对所做更改的描述。
+合并请求通常用作贡献者对仓库贡献代码的方式，仓库的维护者可以通过对合并请求进行审查来决定是否接受这些更改。
+
+## 创建合并请求
+
+要创建合并请求，您需要遵循以下步骤：
+
+1. **Fork 仓库** - 如果您没有直接对仓库进行更改的权限，您需要将仓库 fork 到您自己的账户中。
+   这将创建一个您可以对其进行更改的仓库副本。
+
+2. **创建分支（可选）** - 在 fork 的仓库中创建一个新分支，该分支包含您要提出的更改。
+   给分支取一个描述性的名称，以指示更改的内容。
+
+3. **进行更改** - 进行您想要的更改，提交并将其推送到 fork 的仓库中。
+
+4. **创建合并请求** - 转到原始仓库并转到“合并请求”选项卡。单击“新建合并请求”按钮，并将您的新分支选择为源分支。
+   为您的合并请求输入描述性标题和描述，然后单击“创建合并请求”。
+
+## 评审合并请求
+
+创建合并请求后，将触发评审流程。仓库的维护者将收到合并请求的通知，并可以审查所做的更改。
+他们可以留下评论、请求更改或批准更改。
+
+如果维护者请求更改，您需要在分支中进行这些更改，并将更改推送到 fork 的仓库中。
+合并请求将自动使用新更改进行更新。
+
+如果维护者批准更改，他们可以将合并请求合并到仓库中。
+
+## 关闭合并请求
+
+如果您不接受该合并请求，您可以关闭它。
+要关闭合并请求，请转到打开的合并请求并单击“关闭合并请求”按钮。这将关闭合并请求并且不会将其合并。
+
+## 使用“Work In Progress”标记
+
+在合并请求中使用“Work In Progress”标记可以防止合并请求被意外合并。
+要将合并请求标记为“Work In Progress”，您必须在其标题中添加前缀`WIP:`或`[WIP]`（不区分大小写）。
+标记前缀可以在您的`app.ini`文件中进行配置：
+
+```
+[repository.pull-request]
+WORK_IN_PROGRESS_PREFIXES=WIP:,[WIP]
+```
+
+列表的第一个值将用于 helpers 程序。
+
+## 合并请求模板
+
+有关合并请求模板的更多信息请您移步 : [工单与合并请求模板](usage/issue-pull-request-templates.md)
diff --git a/docs/document/usage/push.md b/docs/document/usage/push.md
new file mode 100644
index 0000000..bf55b78
--- /dev/null
+++ b/docs/document/usage/push.md
@@ -0,0 +1,61 @@
+---
+date: "2023-05-23T09:00:00+08:00"
+slug: "push"
+sidebar_position: 15
+aliases:
+  - /zh-cn/push-to-create
+  - /zh-cn/push-options
+---
+
+# 推送
+
+在将提交推送到 Gitea 服务器时，还有一些额外的功能。
+
+## 通过推送打开 PR
+
+当您第一次将提交推送到非默认分支时，您将收到一个链接，您可以单击该链接访问分支与主分支的比较页面。
+从那里，您可以轻松创建一个拉取请求，即使您想要将其目标指向另一个分支。
+
+![Gitea 推送提示](../../static//gitea-push-hint.png)
+
+## 推送选项
+
+在 Gitea `1.13` 版本中，添加了对一些 [推送选项](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt) 的支持。
+
+### 支持的选项
+
+- `repo.private` (true|false) - 更改仓库的可见性。
+
+  这在与 push-to-create 结合使用时特别有用。
+
+- `repo.template` (true|false) - 更改仓库是否为模板。
+
+将仓库的可见性更改为公开的示例：
+
+```shell
+git push -o repo.private=false -u origin main
+```
+
+## 推送创建
+
+推送创建是一项功能，允许您将提交推送到在 Gitea 中尚不存在的仓库。这对于自动化和允许用户创建仓库而无需通过 Web 界面非常有用。此功能默认处于禁用状态。
+
+### 启用推送创建
+
+在 `app.ini` 文件中，将 `ENABLE_PUSH_CREATE_USER` 设置为 `true`，如果您希望允许用户在自己的用户帐户和所属的组织中创建仓库，将 `ENABLE_PUSH_CREATE_ORG` 设置为 `true`。重新启动 Gitea 以使更改生效。您可以在 [配置速查表](../administration/config-cheat-sheet.md#仓库) 中了解有关这两个选项的更多信息。
+
+### 使用推送创建
+
+假设您在当前目录中有一个 git 仓库，您可以通过运行以下命令将提交推送到在 Gitea 中尚不存在的仓库：
+
+```shell
+# 添加要推送到的远程仓库
+git remote add origin git@{domain}:{username}/{尚不存在的仓库名称}.git
+
+# 推送到远程仓库
+git push -u origin main
+```
+
+这假设您使用的是 SSH 远程，但您也可以使用 HTTPS 远程。
+
+推送创建将默认使用 `app.ini` 中定义的可见性 `DEFAULT_PUSH_CREATE_PRIVATE`。
diff --git a/docs/document/usage/repo-mirror.md b/docs/document/usage/repo-mirror.md
new file mode 100644
index 0000000..b89df30
--- /dev/null
+++ b/docs/document/usage/repo-mirror.md
@@ -0,0 +1,98 @@
+---
+date: "2023-05-23T09:00:00+08:00"
+slug: "repo-mirror"
+sidebar_position: 45
+aliases:
+  - /zh-cn/repo-mirror
+---
+
+# 仓库镜像
+
+仓库镜像允许将仓库与外部源之间进行镜像。您可以使用它在仓库之间镜像分支、标签和提交。
+
+## 使用场景
+
+以下是一些仓库镜像的可能使用场景：
+
+- 您迁移到了 Gitea，但仍需要在其他源中保留您的项目。在这种情况下，您可以简单地设置它以进行镜像到 Gitea（拉取），这样您的 Gitea 实例中就可以获取到所有必要的提交历史、标签和分支。
+- 您在其他源中有一些旧项目，您不再主动使用，但出于归档目的不想删除。在这种情况下，您可以创建一个推送镜像，以便您的活跃的 Gitea 仓库可以将其更改推送到旧位置。
+
+## 从远程仓库拉取
+
+对于现有的远程仓库，您可以按照以下步骤设置拉取镜像：
+
+1. 在右上角的“创建...”菜单中选择“迁移外部仓库”。
+2. 选择远程仓库服务。
+3. 输入仓库的 URL。
+4. 如果仓库需要身份验证，请填写您的身份验证信息。
+5. 选中“该仓库将是一个镜像”复选框。
+6. 选择“迁移仓库”以保存配置。
+
+现在，该仓库会定期从远程仓库进行镜像。您可以通过在仓库设置中选择“立即同步”来强制进行同步。
+
+:::warning
+:exclamation::exclamation: **注意：**您只能为尚不存在于您的实例上的仓库设置拉取镜像。一旦仓库创建成功，您就无法再将其转换为拉取镜像。:exclamation::exclamation:
+:::
+
+## 推送到远程仓库
+
+对于现有的仓库，您可以按照以下步骤设置推送镜像：
+
+1. 在仓库中，转到**设置** > **仓库**，然后进入**镜像设置**部分。
+2. 输入一个仓库的 URL。
+3. 如果仓库需要身份验证，请展开**授权**部分并填写您的身份验证信息。请注意，所请求的**密码**也可以是您的访问令牌。
+4. 选择**添加推送镜像**以保存配置。
+
+该仓库现在会定期镜像到远程仓库。您可以通过选择**立即同步**来强制同步。如果出现错误，会显示一条消息帮助您解决问题。
+
+:::warning
+:exclamation::exclamation: **注意：** 这将强制推送到远程仓库。这将覆盖远程仓库中的任何更改！ :exclamation::exclamation:
+:::
+
+### 从 Gitea 向 GitHub 设置推送镜像
+
+要从 Gitea 设置镜像到 GitHub，您需要按照以下步骤进行操作：
+
+1. 创建一个具有选中 _public_repo_ 选项的 [GitHub 个人访问令牌](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token)。
+2. 在 GitHub 上创建一个同名的仓库。与 Gitea 不同，GitHub 不支持通过推送到远程来创建仓库。如果您的现有远程仓库与您的 Gitea 仓库具有相同的提交历史，您也可以使用现有的远程仓库。
+3. 在您的 Gitea 仓库设置中，填写**Git 远程仓库 URL**：`https://github.com/<your_github_group>/<your_github_project>.git`。
+4. 使用您的 GitHub 用户名填写**授权**字段，并将个人访问令牌作为**密码**。
+5. （可选，适用于 Gitea 1.18+）选择`当推送新提交时同步`，这样一旦有更改，镜像将会及时更新。如果您愿意，您还可以禁用定期同步。
+6. 选择**添加推送镜像**以保存配置。
+
+仓库会很快进行推送。要强制推送，请选择**立即同步**按钮。
+
+### 从 Gitea 向 GitLab 设置推送镜像
+
+要从 Gitea 设置镜像到 GitLab，您需要按照以下步骤进行操作：
+
+1. 创建具有 _write_repository_ 作用域的 [GitLab 个人访问令牌](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)。
+2. 填写**Git 远程仓库 URL**：`https://<destination host>/<your_gitlab_group_or_name>/<your_gitlab_project>.git`。
+3. 在**授权**字段中填写 `oauth2` 作为**用户名**，并将您的 GitLab 个人访问令牌作为**密码**。
+4. 选择**添加推送镜像**以保存配置。
+
+仓库会很快进行推送。要强制推送，请选择**立即同步**按钮。
+
+### 从 Gitea 向 Bitbucket 设置推送镜像
+
+要从 Gitea 设置镜像到 Bitbucket，您需要按照以下步骤进行操作：
+
+1. 创建一个具有选中 _Repository Write_ 选项的 [Bitbucket 应用密码](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/)。
+2. 填写**Git 远程仓库 URL**：`https://bitbucket.org/<your_bitbucket_group_or_name>/<your_bitbucket_project>.git`。
+3. 使用您的 Bitbucket 用户名填写**授权**字段，并将应用密码作为**密码**。
+4. 选择**添加推送镜像**以保存配置。
+
+仓库会很快进行推送。要强制推送，请选择**立即同步**按钮。
+
+### 镜像现有的 ssh 仓库
+
+当前，Gitea 不支持从 ssh 仓库进行镜像。如果您想要镜像一个 ssh 仓库，您需要将其转换为 http 仓库。您可以使用以下命令将现有的 ssh 仓库转换为 http 仓库：
+
+1. 确保运行 gitea 的用户有权限访问您试图从 shell 镜像到的 git 仓库。
+2. 在 Web 界面的版本库设置 > git 钩子中为镜像添加一个接收后钩子。
+
+```
+#!/usr/bin/env bash
+git push --mirror --quiet git@github.com:username/repository.git &>/dev/null &
+echo "GitHub mirror initiated .."
+```
diff --git a/docs/document/usage/template-repositories.md b/docs/document/usage/template-repositories.md
new file mode 100644
index 0000000..f9bc174
--- /dev/null
+++ b/docs/document/usage/template-repositories.md
@@ -0,0 +1,76 @@
+---
+date: "2023-05-23T09:00:00+08:00"
+slug: "template-repositories"
+sidebar_position: 14
+aliases:
+  - /zh-cn/template-repositories
+---
+
+# 模板仓库
+
+Gitea `1.11.0` 及以上版本引入了模板仓库，并且其中一个实现的功能是自动展开模板文件中的特定变量。
+
+要告诉 Gitea 哪些文件需要展开，您必须在模板仓库的 `.gitea` 目录中包含一个 `template` 文件。
+
+Gitea 使用 [gobwas/glob](https://github.com/gobwas/glob) 作为其 glob 语法。它与传统的 `.gitignore` 语法非常相似，但可能存在细微的差异。
+
+## `.gitea/template` 文件示例
+
+所有路径都是相对于仓库的根目录
+
+```gitignore
+# 仓库中的所有 .go 文件
+**.go
+
+# text 目录中的所有文本文件
+text/*.txt
+
+# 特定文件
+a/b/c/d.json
+
+# 匹配批处理文件的大小写变体
+**.[bB][aA][tT]
+```
+
+**注意：** 当从模板生成仓库时，`.gitea` 目录中的 `template` 文件将被删除。
+
+## 参数展开
+
+在与上述通配符匹配的任何文件中，将会扩展某些变量。
+
+文件名和路径的匹配也可以被扩展，并且会经过谨慎的清理处理，以支持跨平台的文件系统。
+
+所有变量都必须采用`$VAR`或`${VAR}`的形式。要转义扩展，使用双重`$$`，例如`$$VAR`或`$${VAR}`。
+
+| 变量                 | 扩展为                        | 可转换 |
+| -------------------- | ----------------------------- | ------ |
+| REPO_NAME            | 生成的仓库名称                | ✓      |
+| TEMPLATE_NAME        | 模板仓库名称                  | ✓      |
+| REPO_DESCRIPTION     | 生成的仓库描述                | ✘      |
+| TEMPLATE_DESCRIPTION | 模板仓库描述                  | ✘      |
+| REPO_OWNER           | 生成的仓库所有者              | ✓      |
+| TEMPLATE_OWNER       | 模板仓库所有者                | ✓      |
+| REPO_LINK            | 生成的仓库链接                | ✘      |
+| TEMPLATE_LINK        | 模板仓库链接                  | ✘      |
+| REPO_HTTPS_URL       | 生成的仓库的 HTTP(S) 克隆链接 | ✘      |
+| TEMPLATE_HTTPS_URL   | 模板仓库的 HTTP(S) 克隆链接   | ✘      |
+| REPO_SSH_URL         | 生成的仓库的 SSH 克隆链接     | ✘      |
+| TEMPLATE_SSH_URL     | 模板仓库的 SSH 克隆链接       | ✘      |
+
+## 转换器 :robot:
+
+Gitea `1.12.0` 添加了一些转换器以应用于上述适用的变量。
+
+例如，要以 `PASCAL`-case 获取 `REPO_NAME`，你的模板应使用 `${REPO_NAME_PASCAL}`
+
+将 `go-sdk` 传递给可用的转换器的效果如下...
+
+| 转换器 | 效果   |
+| ------ | ------ |
+| SNAKE  | go_sdk |
+| KEBAB  | go-sdk |
+| CAMEL  | goSdk  |
+| PASCAL | GoSdk  |
+| LOWER  | go-sdk |
+| UPPER  | GO-SDK |
+| TITLE  | Go-Sdk |
diff --git a/docs/document/usage/webhooks.md b/docs/document/usage/webhooks.md
new file mode 100644
index 0000000..9210f0b
--- /dev/null
+++ b/docs/document/usage/webhooks.md
@@ -0,0 +1,185 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+slug: "webhooks"
+sidebar_position: 30
+aliases:
+  - /zh-cn/webhooks
+---
+
+# Webhooks
+
+Gitea 支持用于仓库事件的 Webhooks。这可以在仓库管理员在设置页面 `/:username/:reponame/settings/hooks` 中进行配置。Webhooks 还可以基于组织和整个系统进行配置。
+所有事件推送都是 POST 请求。目前支持：
+
+- Gitea (也可以是 GET 请求)
+- Gogs
+- Slack
+- Discord
+- Dingtalk（钉钉）
+- Telegram
+- Microsoft Teams
+- Feishu
+- Wechatwork（企业微信）
+- Packagist
+
+### 事件信息
+
+**警告**：自 Gitea 1.13.0 版起，payload 中的 `secret` 字段已被弃用，并将在 1.14.0 版中移除：https://github.com/go-gitea/gitea/issues/11755
+
+以下是 Gitea 将发送给 payload URL 的事件信息示例：
+
+```http
+X-GitHub-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
+X-GitHub-Event: push
+X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
+X-Gogs-Event: push
+X-Gitea-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
+X-Gitea-Event: push
+```
+
+```json
+{
+  "secret": "3gEsCfjlV2ugRwgpU#w1*WaW*wa4NXgGmpCfkbG3",
+  "ref": "refs/heads/develop",
+  "before": "28e1879d029cb852e4844d9c718537df08844e03",
+  "after": "bffeb74224043ba2feb48d137756c8a9331c449a",
+  "compare_url": "http://localhost:3000/gitea/webhooks/compare/28e1879d029cb852e4844d9c718537df08844e03...bffeb74224043ba2feb48d137756c8a9331c449a",
+  "commits": [
+    {
+      "id": "bffeb74224043ba2feb48d137756c8a9331c449a",
+      "message": "Webhooks Yay!",
+      "url": "http://localhost:3000/gitea/webhooks/commit/bffeb74224043ba2feb48d137756c8a9331c449a",
+      "author": {
+        "name": "Gitea",
+        "email": "someone@gitea.io",
+        "username": "gitea"
+      },
+      "committer": {
+        "name": "Gitea",
+        "email": "someone@gitea.io",
+        "username": "gitea"
+      },
+      "timestamp": "2017-03-13T13:52:11-04:00"
+    }
+  ],
+  "repository": {
+    "id": 140,
+    "owner": {
+      "id": 1,
+      "login": "gitea",
+      "full_name": "Gitea",
+      "email": "someone@gitea.io",
+      "avatar_url": "https://localhost:3000/avatars/1",
+      "username": "gitea"
+    },
+    "name": "webhooks",
+    "full_name": "gitea/webhooks",
+    "description": "",
+    "private": false,
+    "fork": false,
+    "html_url": "http://localhost:3000/gitea/webhooks",
+    "ssh_url": "ssh://gitea@localhost:2222/gitea/webhooks.git",
+    "clone_url": "http://localhost:3000/gitea/webhooks.git",
+    "website": "",
+    "stars_count": 0,
+    "forks_count": 1,
+    "watchers_count": 1,
+    "open_issues_count": 7,
+    "default_branch": "master",
+    "created_at": "2017-02-26T04:29:06-05:00",
+    "updated_at": "2017-03-13T13:51:58-04:00"
+  },
+  "pusher": {
+    "id": 1,
+    "login": "gitea",
+    "full_name": "Gitea",
+    "email": "someone@gitea.io",
+    "avatar_url": "https://localhost:3000/avatars/1",
+    "username": "gitea"
+  },
+  "sender": {
+    "id": 1,
+    "login": "gitea",
+    "full_name": "Gitea",
+    "email": "someone@gitea.io",
+    "avatar_url": "https://localhost:3000/avatars/1",
+    "username": "gitea"
+  }
+}
+```
+
+### 示例
+
+这是一个示例，演示如何使用 Webhooks 在推送请求到达仓库时运行一个 php 脚本。
+在你的仓库设置中，在 Webhooks 下，设置一个如下的 Gitea webhook：
+
+- 目标 URL：http://mydomain.com/webhook.php
+- HTTP 方法：POST
+- POST Content Type：application/json
+- Secret：123
+- 触发条件：推送事件
+- 激活：勾选
+
+现在在你的服务器上创建 php 文件 webhook.php。
+
+```php
+<?php
+
+$secret_key = '123';
+
+// check for POST request
+if ($_SERVER['REQUEST_METHOD'] != 'POST') {
+    error_log('FAILED - not POST - '. $_SERVER['REQUEST_METHOD']);
+    exit();
+}
+
+// get content type
+$content_type = isset($_SERVER['CONTENT_TYPE']) ? strtolower(trim($_SERVER['CONTENT_TYPE'])) : '';
+
+if ($content_type != 'application/json') {
+    error_log('FAILED - not application/json - '. $content_type);
+    exit();
+}
+
+// get payload
+$payload = trim(file_get_contents("php://input"));
+
+if (empty($payload)) {
+    error_log('FAILED - no payload');
+    exit();
+}
+
+// get header signature
+$header_signature = isset($_SERVER['HTTP_X_GITEA_SIGNATURE']) ? $_SERVER['HTTP_X_GITEA_SIGNATURE'] : '';
+
+if (empty($header_signature)) {
+    error_log('FAILED - header signature missing');
+    exit();
+}
+
+// calculate payload signature
+$payload_signature = hash_hmac('sha256', $payload, $secret_key, false);
+
+// check payload signature against header signature
+if ($header_signature !== $payload_signature) {
+    error_log('FAILED - payload signature');
+    exit();
+}
+
+// convert json to array
+$decoded = json_decode($payload, true);
+
+// check for json decode errors
+if (json_last_error() !== JSON_ERROR_NONE) {
+    error_log('FAILED - json decode - '. json_last_error());
+    exit();
+}
+
+// success, do something
+```
+
+在 Webhook 设置中有一个“测试推送（Test Delivery）”按钮，可以测试配置，还有一个“最近推送记录（Recent Deliveries）”的列表。
+
+### 授权头（Authorization header）
+
+**从 1.19 版本开始**，Gitea 的 Webhook 可以配置为向 Webhook 目标发送一个 [授权头（authorization header）](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)。