chore(docker-compose): remove obsolete version parament & remove useless default external=false (#288 )

- Removed deprecated `version` key from docker-compose.yaml - Cleaned up unnecessary `external: false` declarations for networks/volumes Signed-off-by: Snowball_233 <[email protected]> Reviewed-on: https://gitea.com/gitea/docs/pulls/288 Reviewed-by: techknowlogick <[email protected]> Co-authored-by: Snowball_233 <[email protected]> Co-committed-by: Snowball_233 <[email protected]>
Fix typo in CAD preview supported extensions list (#286 ) (#287 )
2026-11-15 06:13:46 +00:00 · 2025-10-30 14:07:06 +00:00 · 2025-10-28 01:40:09 +00:00 · 2025-10-25 21:03:20 -07:00 · 2025-10-25 03:47:14 +00:00 · 2025-10-23 17:55:14 +00:00
1131 changed files with 168706 additions and 4134 deletions
@@ -8,10 +8,10 @@ on:

 jobs:
  build-docs:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v6
        with:
          node-version: 20
          cache: npm
@@ -21,7 +21,7 @@ jobs:
          pip install awscli
      - name: prepare awesome list
        run: |
-          make prepare-awesome-latest prepare-awesome\#22 prepare-awesome\#21 prepare-awesome\#20 prepare-awesome\#19
+          make prepare-awesome-latest prepare-awesome\#23 prepare-awesome\#22 prepare-awesome\#21 prepare-awesome\#20 prepare-awesome\#19
      - name: Cache ~/.npm for npm ci
        uses: actions/cache@v4
        with:
@@ -37,7 +37,7 @@ jobs:
        run: |
          make build
      - name: aws credential configure
-        uses: aws-actions/configure-aws-credentials@v4
+        uses: aws-actions/configure-aws-credentials@v5
        with:
          aws-access-key-id: ${{ secrets.AWS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY}}
@@ -7,14 +7,14 @@ jobs:
  build-docs:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v6
        with:
          node-version: 20
          cache: npm
      - name: prepare awesome list
        run: |
-          make prepare-awesome-latest prepare-awesome\#22 prepare-awesome\#21 prepare-awesome\#20 prepare-awesome\#19
+          make prepare-awesome-latest prepare-awesome\#23 prepare-awesome\#22 prepare-awesome\#21 prepare-awesome\#20 prepare-awesome\#19
      - name: Cache ~/.npm for npm ci
        uses: actions/cache@v4
        with:
@@ -9,15 +9,23 @@ jobs:
  update-swagger:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
      - run: |
-          wget https://github.com/go-gitea/gitea/blob/main/templates/swagger/v1_json.tmpl
-          sed -i "$@" 's/"version": "{{AppVer | JSEscape | Safe}}"/"version": "dev"/' static/swagger-latest.json
-          rm v1_json.tmpl
+          wget https://raw.githubusercontent.com/go-gitea/gitea/refs/heads/main/templates/swagger/v1_json.tmpl
+          sed -i "$@" 's\"version": "{{AppVer | JSEscape}}"\"version": "dev"\' v1_json.tmpl
+          sed -i "$@" 's\"basePath": "{{AppSubUrl | JSEscape}}/api/v1"\"basePath": "https://gitea.com/api/v1"\' v1_json.tmpl
+          mv v1_json.tmpl static/swagger-latest.json

-          wget https://github.com/go-gitea/gitea/blob/v1.22.4/templates/swagger/v1_json.tmpl
-          sed -i "$@" 's/"version": "{{AppVer | JSEscape | Safe}}"/"version": "1.22.6"/' static/swagger-22.json
-          rm v1_json.tmpl
+          for ver in '1.24.7' '1.23.8' '1.22.6' '1.21.11' '1.20.6' '1.19.4'; do
+            wget https://raw.githubusercontent.com/go-gitea/gitea/refs/tags/v${ver}/templates/swagger/v1_json.tmpl
+            sed -i "$@" "s|\"version\": \"{{AppVer \| JSEscape}}\"|\"version\": \"${ver}\"|" v1_json.tmpl
+            sed -i "$@" 's\"basePath": "{{AppSubUrl | JSEscape}}/api/v1"\"basePath": "https://gitea.com/api/v1"\' v1_json.tmpl
+            # for version < 1.21.11
+            sed -i "$@" "s|\"version\": \"{{AppVer \| JSEscape \| Safe}}\"|\"version\": \"${ver}\"|" v1_json.tmpl
+            sed -i "$@" 's\"basePath": "{{AppSubUrl | JSEscape | Safe}}/api/v1"\"basePath": "https://gitea.com/api/v1"\' v1_json.tmpl
+            minor=$(echo "$ver" | cut -d '.' -f 2)
+            mv v1_json.tmpl static/swagger-$minor.json
+          done

          if ! [[ $(git diff --shortstat) ]]; then exit 0; fi
          git config --global user.name "Gitea Bot"
@@ -27,7 +27,7 @@ install:
 	npm install

 .PHONY: prepare-docs
-prepare-docs: install prepare-awesome-latest prepare-awesome\#19 prepare-awesome\#20 prepare-awesome\#21 prepare-awesome\#22
+prepare-docs: install prepare-awesome-latest prepare-awesome\#19 prepare-awesome\#20 prepare-awesome\#21 prepare-awesome\#22 prepare-awesome\#23 prepare-awesome\#24

 .PHONY: build
 build:
@@ -50,3 +50,5 @@ clean:
 	rm -rf static/swagger-20.json
 	rm -rf static/swagger-21.json
 	rm -rf static/swagger-22.json
+	rm -rf static/swagger-23.json
+	rm -rf static/swagger-24.json
@@ -325,6 +325,7 @@ in the current directory.
  - `--skip-attachment-data`: Skip dumping of attachment data. Optional.
  - `--skip-package-data`: Skip dumping of package data. Optional.
  - `--skip-log`: Skip dumping of log data. Optional.
+  - `--skip-index`: Skip dumping of Bleve indexer data. Optional. Applies only for bleve.
  - `--database`, `-d`: Specify the database SQL syntax. Optional (supported arguments: sqlite3, mysql, mssql, postgres).
  - `--verbose`, `-V`: If provided, shows additional details. Optional.
  - `--type`: Set the dump output format. Optional. (formats: zip, tar, tar.sz, tar.gz, tar.xz, tar.bz2, tar.br, tar.lz4, tar.zst default: zip).
@@ -1,5 +1,5 @@
 ---
-date: "2016-12-26T16:00:00+02:00"
+date: "2025-10-26T00:00:00+00:00"
 slug: "config-cheat-sheet"
 sidebar_position: 30
 aliases:
@@ -99,7 +99,7 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build
   default is not to present.

   :::warning
-   This maybe harmful to you website if you do not give it a right value.
+   This maybe harmful to your website if you do not give it a right value.
   :::

 - `DEFAULT_CLOSE_ISSUES_VIA_COMMITS_IN_ANY_BRANCH`:  **false**: Close an issue if a commit on a non default branch marks it as closed.
@@ -224,6 +224,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 - `DEFAULT_THEME`: **gitea-auto**: Set the default theme for the Gitea installation, custom themes could be provided by `{CustomPath}/public/assets/css/theme-*.css`.
 - `SHOW_USER_EMAIL`: **true**: Whether the email of the user should be shown in the Explore Users page.
 - `THEMES`: **_empty_**: All available themes by `{CustomPath}/public/assets/css/theme-*.css`. Allow users select personalized themes.
+- `FILE_ICON_THEME`: **material**: The icons for file list (basic/material).
 - `MAX_DISPLAY_FILE_SIZE`: **8388608**: Max size of files to be displayed (default is 8MiB)
 - `AMBIGUOUS_UNICODE_DETECTION`: **true**: Detect ambiguous unicode characters in file contents and show warnings on the UI
 - `REACTIONS`: All available reactions users can choose on issues/prs and comments
@@ -233,6 +234,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 - `CUSTOM_EMOJIS`: **gitea, codeberg, gitlab, git, github, gogs**: Additional Emojis not defined in the utf8 standard.
    By default, we support Gitea (:gitea:), to add more copy them to public/assets/img/emoji/emoji_name.png and
    add it to this config.
+- `ENABLED_EMOJIS`: **_empty_**: Comma separated list of enabled emojis, for example: "smile, thumbsup, thumbsdown". Leave it empty to enable all emojis.
 - `DEFAULT_SHOW_FULL_NAME`: **false**: Whether the full name of the users should be shown where possible. If the full name isn't set, the username will be used.
 - `SEARCH_REPO_DESCRIPTION`: **true**: Whether to search within description at repository search on explore page.
 - `ONLY_SHOW_RELEVANT_REPOS`: **false**: Whether to only show relevant repos on the explore page when no keyword is specified and default sorting is used.
@@ -276,17 +278,23 @@ The following configuration set `Content-Type: application/vnd.android.package-a

 ## Markdown (`markdown`)

- `ENABLE_HARD_LINE_BREAK_IN_COMMENTS`: **true**: Render soft line breaks as hard line breaks in comments, which
-  means a single newline character between paragraphs will cause a line break and adding
-  trailing whitespace to paragraphs is not necessary to force a line break.
- `ENABLE_HARD_LINE_BREAK_IN_DOCUMENTS`: **false**: Render soft line breaks as hard line breaks in documents, which
-  means a single newline character between paragraphs will cause a line break and adding
-  trailing whitespace to paragraphs is not necessary to force a line break.
+- `RENDER_OPTIONS_COMMENT`: **short-issue-pattern, new-line-hard-break**: Customize render options for different contexts.
+  Set to "none" to disable the defaults, or use comma separated list:
+  - short-issue-pattern: recognized "#123" issue reference and render it as a link to the issue
+  - new-line-hard-break: render soft line breaks as hard line breaks, which means a single newline character between
+    paragraphs will cause a line break and adding trailing whitespace to paragraphs is not
+    necessary to force a line break.
+- `RENDER_OPTIONS_WIKI`: **short-issue-pattern**: see also RENDER_OPTIONS_COMMENT
+- `RENDER_OPTIONS_REPO_FILE`: **_empty_**: see also RENDER_OPTIONS_COMMENT
 - `CUSTOM_URL_SCHEMES`: Use a comma separated list (ftp,git,svn) to indicate additional
  URL hyperlinks to be rendered in Markdown. URLs beginning in http and https are
  always displayed. If this entry is empty, all URL schemes are allowed
- `FILE_EXTENSIONS`: **.md,.markdown,.mdown,.mkd,.livemd**: List of file extensions that should be rendered/edited as Markdown. Separate the extensions with a comma. To render files without any extension as markdown, just put a comma.
+- `FILE_EXTENSIONS`: **.md,.markdown,.mdown,.mkd,.livemd**: List of file extensions that should be rendered/edited as Markdown.
+  Separate the extensions with a comma. To render files without any extension as markdown, just put a comma.
 - `ENABLE_MATH`: **true**: Enables detection of `$...$`, `$$...$$`, ``` $`...`$$ ``` blocks as math blocks.
+- `MATH_CODE_BLOCK_DETECTION`: **inline-dollar,block-dollar**: Enable delimiters for math code block detection.
+  Set to "none" to disable all, or use comma separated list: inline-dollar, inline-parentheses, block-dollar, block-square-brackets.
+  Default value follows GitHub.

 ## Server (`server`)

@@ -300,7 +308,12 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 - `DOMAIN`: **localhost**: Domain name of this server.
 - `ROOT_URL`: **`{PROTOCOL}://{DOMAIN}:{HTTP_PORT}/`**:
   Overwrite the automatically generated public URL.
-   This is useful if the internal and the external URL don't match (e.g. in Docker).
+   This is useful if the internal and the external URL don't match (e.g. behind a reverse proxy).
+- `PUBLIC_URL_DETECTION`: **`legacy`**: Controls how to generate the public URL. 
+   Although it defaults to "legacy" (to avoid breaking existing users), most instances should use the "auto" behavior,
+   especially when the Gitea instance needs to be accessed in a container network.
+   - "legacy": generate the public URL by "Host" header if "X-Forwarded-Proto" header exists, otherwise use "ROOT_URL".
+   - "auto": always use "Host" header, and also use "X-Forwarded-Proto" header if it exists. If no "Host" header, use "ROOT_URL".
 - `STATIC_URL_PREFIX`: **_empty_**:
   Overwrite this option to request static resources from a different URL.
   This includes CSS files, images, JS files and web fonts.
@@ -614,6 +627,7 @@ And the following unique queues:
 - `PASSWORD_CHECK_PWN`: **false**: Check [HaveIBeenPwned](https://haveibeenpwned.com/Passwords) to see if a password has been exposed.
 - `SUCCESSFUL_TOKENS_CACHE_SIZE`: **20**: Cache successful token hashes. API tokens are stored in the DB as pbkdf2 hashes however, this means that there is a potentially significant hashing load when there are multiple API operations. This cache will store the successfully hashed tokens in a LRU cache as a balance between performance and security.
 - `DISABLE_QUERY_AUTH_TOKEN`: **false**: Reject API tokens sent in URL query string (Accept Header-based API tokens only). This setting will default to `true` in Gitea 1.23 and be deprecated in Gitea 1.24.
+- `TWO_FACTOR_AUTH`: **_empty_**: set to enforced to enforce two factor authentication. Only available in Gitea 1.24 and later.

 ## Camo (`camo`)

@@ -670,15 +684,20 @@ And the following unique queues:
   :::

 - `REQUIRE_SIGNIN_VIEW`: **false**: Enable this to force users to log in to view any page or to use API.
+   It could be set to "expensive" to block anonymous users accessing some pages which consume a lot of resources,
+   for example: block anonymous AI crawlers from accessing repo code pages.
+   The "expensive" mode is experimental and subject to change.
 - `ENABLE_NOTIFY_MAIL`: **false**: Enable this to send e-mail to watchers of a repository when
   something happens, like creating issues. Requires `Mailer` to be enabled.
 - `ENABLE_BASIC_AUTHENTICATION`: **true**: Disable this to disallow authentication using HTTP
   BASIC and the user's password. Please note if you disable this you will not be able to access the
   tokens API endpoints using a password. Further, this only disables BASIC authentication using the
   password - not tokens or OAuth Basic.
- `ENABLE_PASSWORD_SIGNIN_FORM`: **true**: Show the password login form (for password-based login).
+- `ENABLE_PASSWORD_SIGNIN_FORM`: **true**: Show the password login form (for password-based login),
+   otherwise, only show OAuth2 or passkey login methods if they are enabled.
   If you set it to false, maybe it also needs to set `ENABLE_BASIC_AUTHENTICATION` to false to
   completely disable password-based authentication.
+- `ENABLE_PASSKEY_AUTHENTICATION`: **true**: Allow users to sign-in with a passkey
 - `ENABLE_REVERSE_PROXY_AUTHENTICATION`: **false**: Enable this to allow reverse proxy authentication for web requests
 - `ENABLE_REVERSE_PROXY_AUTHENTICATION_API`: **false**: Enable this to allow reverse proxy authentication for API requests, the reverse proxy is responsible for ensuring that no CSRF is possible.
 - `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION`: **false**: Enable this to allow auto-registration
@@ -736,6 +755,13 @@ And the following unique queues:
 - `DISABLE_ORGANIZATIONS_PAGE`: **false**: Disable the organizations explore page.
 - `DISABLE_CODE_PAGE`: **false**: Disable the code explore page.

+### Request Quality of Service (`qos`)
+
+- `ENABLED`: **false**: Enable request quality of service and overload protection.
+- `MAX_INFLIGHT`: **(dynamic)**: The maximum number of concurrent requests that the server will process before enqueueing new requests. Default is "CpuNum * 4".
+- `MAX_WAITING`: **100**: The maximum number of requests that can be enqueued before new requests will be dropped.
+- `TARGET_WAIT_TIME`: **250ms**: Target maximum wait time a request may be enqueued for. Requests that are enqueued for less than this amount of time will not be dropped. When wait times exceed this amount, a portion of requests will be dropped until wait times have decreased below this amount.
+
 ## SSH Minimum Key Sizes (`ssh.minimum_key_sizes`)

 Define allowed algorithms and their minimum key length (use -1 to disable a type):
@@ -803,6 +829,7 @@ and
 - `SENDMAIL_CONVERT_CRLF`: **true**: Most versions of sendmail prefer LF line endings rather than CRLF line endings. Set this to false if your version of sendmail requires CRLF line endings.
 - `SEND_BUFFER_LEN`: **100**: Buffer length of mailing queue. **DEPRECATED** use `LENGTH` in `[queue.mailer]`
 - `SEND_AS_PLAIN_TEXT`: **false**: Send mails only in plain text, without HTML alternative.
+- `EMBED_ATTACHMENT_IMAGES`: **false**: Embed attached images in base64 format in HTML emails. (for clients that do not load external images or disconnected vpn users still receiving emails; ATTENTION: online webclients like gmail will not show base64 embedded images)

 ## Override Email Headers (`mailer.override_header`)

@@ -979,7 +1006,6 @@ Default templates for project board view:
 - `ENABLED`: **false**: Enable to run all cron tasks periodically with default settings.
 - `RUN_AT_START`: **false**: Run cron tasks at application start-up.
 - `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
-
 - `SCHEDULE` accept formats
  - Full crontab specs, e.g. `* * * * * ?`
  - Descriptors, e.g. `@midnight`, `@every 1h30m` ...
@@ -991,25 +1017,34 @@ Default templates for project board view:

 - `ENABLED`: **true**: Enable service.
 - `RUN_AT_START`: **true**: Run tasks at start up time (if ENABLED).
+- `NOTICE_ON_SUCCESS`: **false**: Whether to emit notice on successful execution too
 - `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
 - `OLDER_THAN`: **24h**: Archives created more than `OLDER_THAN` ago are subject to deletion, e.g. `12h`.

 #### Cron - Update Mirrors (`cron.update_mirrors`)

+- `ENABLED`: **true**: Enable running Update mirrors task periodically.
 - `SCHEDULE`: **@every 10m**: Cron syntax for scheduling update mirrors, e.g. `@every 3h`.
+- `RUN_AT_START`: **false**: Run Update mirrors task when Gitea starts.
+- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
 - `PULL_LIMIT`: **50**: Limit the number of mirrors added to the queue to this number (negative values mean no limit, 0 will result in no mirrors being queued effectively disabling pull mirror updating).
 - `PUSH_LIMIT`: **50**: Limit the number of mirrors added to the queue to this number (negative values mean no limit, 0 will result in no mirrors being queued effectively disabling push mirror updating).

 #### Cron - Repository Health Check (`cron.repo_health_check`)

+- `ENABLED`: **true**: Enable running Update mirrors task periodically.
 - `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository health check.
+- `RUN_AT_START`: **false**: Run Update mirrors task when Gitea starts.
+- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
 - `TIMEOUT`: **60s**: Time duration syntax for health check execution timeout.
 - `ARGS`: **_empty_**: Arguments for command `git fsck`, e.g. `--unreachable --tags`. See more on http://git-scm.com/docs/git-fsck

 #### Cron - Repository Statistics Check (`cron.check_repo_stats`)

- `RUN_AT_START`: **true**: Run repository statistics check at start time.
 - `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository statistics check.
+- `ENABLED`: **true**: Enable running Update mirrors task periodically.
+- `RUN_AT_START`: **true**: Run Update mirrors task when Gitea starts.
+- `NOTICE_ON_SUCCESS`: **false**: Notice if not success

 #### Cron - Cleanup hook_task Table (`cron.cleanup_hook_task_table`)

@@ -1030,10 +1065,20 @@ Default templates for project board view:

 #### Cron - Update Migration Poster ID (`cron.update_migration_poster_id`)

+Update migrated repositories' issues and comments' posterid, it will always attempt synchronization when the instance starts.
+
+- `ENABLED`: **true**: Enable update migration poster id job.
+- `RUN_AT_START`: **true**: Update migrated repositories' issues and comments' posterid when starting server
+- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
 - `SCHEDULE`: **@midnight** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts.

 #### Cron - Sync External Users (`cron.sync_external_users`)

+Synchronize external user data (only LDAP user synchronization is supported)
+
+- `ENABLED`: **true**: Enable synchronize external user data job
+- `RUN_AT_START`: **false**: Synchronize external user data when starting server
+- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
 - `SCHEDULE`: **@midnight** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts.
 - `UPDATE_EXISTING`: **true**: Create new users, update existing user data and disable users that are not in external source anymore (default) or only create new users if UPDATE_EXISTING is set to false.

@@ -1213,7 +1258,9 @@ This section only does "set" config, a removed config key from this section won'

 ## Markup (`markup`)

- `MERMAID_MAX_SOURCE_CHARACTERS`: **5000**: Set the maximum size of a Mermaid source. (Set to -1 to disable)
+- `MERMAID_MAX_SOURCE_CHARACTERS`: **50000**: Set the maximum size of a Mermaid source. (Set to -1 to disable)
+
+## Markup External Render (`markup.external-render-name`)

 Gitea can support Markup using external tools. The example below will add a markup named `asciidoc`.

@@ -1227,7 +1274,6 @@ IS_INPUT_FILE = false
 ```

 - ENABLED: **false** Enable markup support; set to **true** to enable this renderer.
- NEED\_POSTPROCESS: **true** set to **true** to replace links / sha1 and etc.
 - FILE\_EXTENSIONS: **_empty_** List of file extensions that should be rendered by an external
   command. Multiple extensions needs a comma as splitter.
 - RENDER\_COMMAND: External command to render all matching extensions.
@@ -1236,6 +1282,10 @@ IS_INPUT_FILE = false
  - sanitized: Sanitize the content and render it inside current page, default to only allow a few HTML tags and attributes. Customized sanitizer rules can be defined in `[markup.sanitizer.*]`.
  - no-sanitizer: Disable the sanitizer and render the content inside current page. It's **insecure** and may lead to XSS attack if the content contains malicious code.
  - iframe: Render the content in a separate standalone page and embed it into current page by iframe. The iframe is in sandbox mode with same-origin disabled, and the JS code are safely isolated from parent page.
+- RENDER_CONTENT_SANDBOX: **_empty_** The sandbox applied to the iframe and Content-Security-Policy header when RENDER_CONTENT_MODE is `iframe`. It defaults to a safe set of "allow-*" restrictions (space separated). You can also set it by your requirements or use "disabled" to disable the sandbox completely. When set it, make sure there is no security risk:
+    - PDF-only content: generally safe to use "disabled", and it needs to be "disabled" because PDF only renders with no sandbox.
+    - HTML content with JS: if the "RENDER_COMMAND" can guarantee there is no XSS, then it is safe, otherwise, you need to fine tune the "allow-*" restrictions.
+- NEED_POST_PROCESS: **false** Whether post-process the rendered HTML content, including: resolve relative links and image sources, recognizing issue/commit references, escaping invisible characters, mentioning users, rendering permlink code blocks, replacing emoji shorthands, etc. By default, this is true when RENDER_CONTENT_MODE is `sanitized`, otherwise false.

 Two special environment variables are passed to the render command:

@@ -9,7 +9,7 @@ aliases:
 # Customizing Gitea

 Customizing Gitea is typically done using the `CustomPath` folder - by default this is
-the `custom` folder from the working directory (WorkPath), but may be different if your build has
+the `custom` folder from the working directory (WorkPath), but may be different if your [installation](../installation/installation.md) has
 set this differently. This is the central place to override configuration settings,
 templates, etc. You can check the `CustomPath` using `gitea help`. You can also find
 the path on the _Configuration_ tab in the _Site Administration_ page. You can override
@@ -23,7 +23,7 @@ the Linux Filesystem Standard. Gitea will attempt to create required folders, in
 `custom/`. Distributions may provide a symlink for `custom` using `/etc/gitea/`.

 Application settings can be found in file `CustomConf` which is by default,
-`$GITEA_CUSTOM/conf/app.ini` but may be different if your build has set this differently.
+`$GITEA_CUSTOM/conf/app.ini` but may be different if your [installation](../installation/installation.md) has set this differently.
 Again `gitea help` will allow you review this variable and you can override it using the
 `--config` option on the `gitea` binary.

@@ -165,52 +165,180 @@ Alice <-- Bob: Another authentication Response

 The script will detect tags with `class="language-plantuml"`, but you can change this by providing a second argument to `parsePlantumlCodeBlocks`.

-### Example: STL Preview
+### Example: CAD Files Preview using Online 3D Viewer

-You can display STL file directly in Gitea by adding:
+You can implement CAD file preview inside your Gitea instance. This implemenation uses [`Online 3D Viewer`](https://github.com/kovacsv/Online3DViewer).
+
+Supports following 3D file formats:
+'3dm', '3ds', '3mf', 'amf', 'bim', 'brep', 'dae', 'fbx', 'fcstd', 'glb',
+'gltf', 'ifc', 'igs', 'iges', 'stp', 'step', 'stl', 'obj', 'off', 'ply', 'wrl'
+(Only v2 for .gltf files)
+
+#### Part 1: Add template
+
+In $GITEA_CUSTOM we need to add our template.
+This template needs to be saved in "$GITEA_CUSTOM/templates/custom/".
+Here create file "footer.tmpl" and add following text into it:
+
+```
+nano $GITEA_CUSTOM/templates/custom/footer.tmpl
+```

 ```html
 <script>
-  function lS(src) {
-    return new Promise(function (resolve, reject) {
-      let s = document.createElement("script");
-      s.src = src;
-      s.addEventListener("load", () => {
-        resolve();
-      });
-      document.body.appendChild(s);
+    function onPageChange() {
+      // Supported 3D file types
+      const fileTypes = ['3dm', '3ds', '3mf', 'amf', 'bim', 'brep', 'dae', 'fbx', 'fcstd', 'glb', 'gltf', 'ifc', 'igs', 'iges', 'stp', 'step', 'stl', 'obj', 'off', 'ply', 'wrl'];
+  
+      // Select matching link
+      const links = Array.from(document.querySelectorAll('a.ui.mini.basic.button'));
+      const link3D = links.find(link => {
+        const href = link.href.toLowerCase();
+        return href.includes('/raw/') && fileTypes.some(ext => href.endsWith(`.${ext}`));
      });
+  
+	if (link3D) {
+	  const existingScript = document.querySelector('script[src="/assets/o3dv/o3dv.min.js"]');
+
+	  const initializeViewer = () => {
+		const fileUrl = link3D.getAttribute('href');
+
+                const fileView = document.querySelector('.file-view');
+
+		if (!fileView) return;
+
+		// Remove only the old viewer container if it exists
+		const oldView3D = document.getElementById('view-3d');
+		if (oldView3D) {
+		  oldView3D.remove();  // safely remove old viewer container div
+		} else {
+		  // No #view-3d, so remove all children inside .file-view
+		  while (fileView.firstChild) {
+		    fileView.removeChild(fileView.firstChild);
+		  }
 		}

-  if ($('.view-raw>a[href$=".stl" i]').length) {
-    $("body").append(
-      '<link href="/assets/Madeleine.js/src/css/Madeleine.css" rel="stylesheet">'
-    );
-    Promise.all([
-      lS("/assets/Madeleine.js/src/lib/stats.js"),
-      lS("/assets/Madeleine.js/src/lib/detector.js"),
-      lS("/assets/Madeleine.js/src/lib/three.min.js"),
-      lS("/assets/Madeleine.js/src/Madeleine.js"),
-    ]).then(function () {
-      $(".view-raw")
-        .attr("id", "view-raw")
-        .attr("style", "padding: 0;margin-bottom: -10px;");
-      new Madeleine({
-        target: "view-raw",
-        data: $('.view-raw>a[href$=".stl" i]').attr("href"),
-        path: "/assets/Madeleine.js/src",
-      });
-      $('.view-raw>a[href$=".stl"]').remove();
+		// Create a new container for the viewer
+		const newView3D = document.createElement('div');
+		  newView3D.id = 'view-3d';
+		  newView3D.style.padding = '0';
+		  newView3D.style.margin = '0';
+		  newView3D.style.flexGrow = '1';
+		  newView3D.style.minHeight = '0';
+		  newView3D.style.width = '100%';
+		
+		const header = document.querySelector('header');
+		const headerHeight = header ? header.offsetHeight : 0;
+
+		newView3D.style.height = `calc(100vh - ${headerHeight}px)`;		
+
+		// Append the new container inside fileView
+		fileView.appendChild(newView3D);
+
+		const parentDiv = document.getElementById('view-3d');
+		if (parentDiv) {
+		  const viewer = new OV.EmbeddedViewer(parentDiv, {
+			backgroundColor: new OV.RGBAColor(59, 68, 76, 0),
+			defaultColor: new OV.RGBColor(200, 200, 200),
+			edgeSettings: new OV.EdgeSettings(false, new OV.RGBColor(0, 0, 0), 1),
+			environmentSettings: new OV.EnvironmentSettings([
+			  '/assets/o3dv/envmaps/fishermans_bastion/negx.jpg',
+			  '/assets/o3dv/envmaps/fishermans_bastion/posx.jpg',
+			  '/assets/o3dv/envmaps/fishermans_bastion/posy.jpg',
+			  '/assets/o3dv/envmaps/fishermans_bastion/negy.jpg',
+			  '/assets/o3dv/envmaps/fishermans_bastion/posz.jpg',
+			  '/assets/o3dv/envmaps/fishermans_bastion/negz.jpg'
+			], false)
 		  });
+
+		  viewer.LoadModelFromUrlList([fileUrl]);
 		}
+	  };
+
+	  if (typeof OV === 'undefined') {
+		if (!existingScript) {
+		  const script = document.createElement('script');
+		  script.onload = initializeViewer;
+		  script.src = '/assets/o3dv/o3dv.min.js';
+		  document.head.appendChild(script);
+		} else {
+		  // Script is loading but OV not yet ready — wait for it
+		  existingScript.addEventListener('load', initializeViewer);
+		}
+	  } else {
+		// OV already loaded
+		initializeViewer();
+	  }
+	}
+    };
+
+    // Run when the page is fully loaded
+    document.addEventListener('DOMContentLoaded', onPageChange); 
+
+    const targetSelector = 'a.ui.mini.basic.button[href*="/raw/"]';
+    let lastHref = null;
+    let timeoutId = null;
+
+    const checkAndRun = () => {
+      const rawLink = document.querySelector(targetSelector);
+      if (!rawLink) return;
+
+      const currentHref = rawLink.getAttribute('href');
+      if (currentHref !== lastHref) {
+        lastHref = currentHref;
+
+        const fileName = currentHref.split('/').pop();
+        console.log('New Raw file link detected after delay:', fileName);
+        
+        onPageChange();
+      }
+    };
+
+    const observer = new MutationObserver(() => {
+      // Delay execution by 300ms after last mutation
+      clearTimeout(timeoutId);
+      timeoutId = setTimeout(checkAndRun, 300);
+    });
+
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true,
+    });
 </script>
 ```

-to the file `templates/custom/footer.tmpl`
+#### Part 2: Add public files

-You also need to download the content of the library [Madeleine.js](https://github.com/beige90/Madeleine.js) and place it under `$GITEA_CUSTOM/public/assets/` folder.
+Now we need to download latest version of O3DV. Go to "$GITEA_CUSTOM/public/assets/".
+Create folder using (and cd into it):

-You should end-up with a folder structure similar to:
+```
+mkdir o3dv
+cd o3dv
+```
+
+Copy latest release zip link from [`GitHub`](https://github.com/kovacsv/Online3DViewer/releases) (v0.16.0 as of now).
+Here use e.g. wget to download the file:
+
+```
+wget https://github.com/kovacsv/Online3DViewer/releases/download/0.16.0/o3dv.zip
+```
+
+Use e.g. unzip to unzip the archive:
+```
+unzip o3dv.zip
+```
+
+#### Part 3: Folder permissions
+
+Now the last thing. Change permissions on the public folder:
+```
+chown -R git:git $GITEA_CUSTOM/public
+```
+
+Now we have everything ready! Restart your gitea instance to apply these changes and test it in your browser.
+
+Sanity check. You should end-up with a folder structure similar to this:

 ```
 $GITEA_CUSTOM/templates
@@ -218,49 +346,14 @@ $GITEA_CUSTOM/templates
    `-- footer.tmpl

 $GITEA_CUSTOM/public/assets/
-- Madeleine.js
-   |-- LICENSE
-   |-- README.md
-   |-- css
-   |   |-- pygment_trac.css
-   |   `-- stylesheet.css
-   |-- examples
-   |   |-- ajax.html
-   |   |-- index.html
-   |   `-- upload.html
-   |-- images
-   |   |-- bg_hr.png
-   |   |-- blacktocat.png
-   |   |-- icon_download.png
-   |   `-- sprite_download.png
-   |-- models
-   |   |-- dino2.stl
-   |   |-- ducati.stl
-   |   |-- gallardo.stl
-   |   |-- lamp.stl
-   |   |-- octocat.stl
-   |   |-- skull.stl
-   |   `-- treefrog.stl
-   `-- src
-       |-- Madeleine.js
-       |-- css
-       |   `-- Madeleine.css
-       |-- icons
-       |   |-- logo.png
-       |   |-- madeleine.eot
-       |   |-- madeleine.svg
-       |   |-- madeleine.ttf
-       |   `-- madeleine.woff
-       `-- lib
-           |-- MadeleineConverter.js
-           |-- MadeleineLoader.js
-           |-- detector.js
-           |-- stats.js
-           `-- three.min.js
+-- o3dv
+   |-- o3dv_0.15.0.zip
+   |-- o3dv.license.md
+   |-- o3dv.min.js
+   |-- envmaps
+    \...
 ```

-Then restart Gitea and open a STL file on your Gitea instance.
-
 ## Customizing Gitea mails

 The `$GITEA_CUSTOM/templates/mail` folder allows changing the body of every mail of Gitea.
@@ -380,13 +473,27 @@ To make a custom theme available to all users:
  The value of `$GITEA_CUSTOM` of your instance can be queried by calling `gitea help` and looking up the value of "CustomPath".
 2. Add `<theme-name>` to the comma-separated list of setting `THEMES` in `app.ini`, or leave `THEMES` empty to allow all themes.

+A custom theme file named `theme-my-theme.css` will be displayed as `my-theme` on the user's theme selection page.
+It could add theme meta information into the custom theme CSS file to provide more information about the theme.
+If a custom theme is a dark theme, please set the global css variable `--is-dark-theme: true` in the `:root` block.
+This allows Gitea to adjust the Monaco code editor's theme accordingly.
+An "auto" theme could be implemented by using "theme-gitea-auto.css" as a reference.
+
+```css
+gitea-theme-meta-info {
+  --theme-display-name: "My Awesome Theme"; /* this theme will be display as "My Awesome Theme" on the UI */
+}
+:root {
+  --is-dark-theme: true; /* if it is a dark theme */
+  --color-primary: #112233;
+  /* more custom theme variables ... */
+}
+```
+
 Community themes are listed in [gitea/awesome-gitea#themes](https://gitea.com/gitea/awesome-gitea#themes).

 The default theme sources can be found [here](https://github.com/go-gitea/gitea/blob/main/web_src/css/themes).

-If your custom theme is considered a dark theme, set the global css variable `--is-dark-theme` to `true`.
-This allows Gitea to adjust the Monaco code editor's theme accordingly.
-
 ## Customizing fonts

 Fonts can be customized using CSS variables:
@@ -10,6 +10,10 @@ aliases:

 Gitea has mailer functionality for sending transactional emails (such as registration confirmation). It can be configured to either use Sendmail (or compatible MTAs like Postfix and msmtp) or directly use SMTP server.

+:::note
+Be sure to set ENABLE_NOTIFY_MAIL=true to allow Gitea to send email notifications. Check the [Config Cheat Sheet](../administration/config-cheat-sheet.md#service-service) for details.
+:::
+
 ## Using Sendmail

 Use `sendmail` command as mailer.
@@ -56,7 +60,7 @@ For the full list of options check the [Config Cheat Sheet](../administration/co
 Authentication is only supported when the SMTP server communication is encrypted with TLS or `HOST=localhost`. TLS encryption can be through:
 :::

- STARTTLS (also known as Opportunistic TLS) via port 587. Initial connection is done over cleartext, but then be upgraded over TLS if the server supports it.
+- STARTTLS (also known as Opportunistic TLS) via port 587 with `PROTOCOL=smtp+starttls`. Initial connection is done over cleartext, but then be upgraded over TLS if the server supports it.
 - SMTPS connection (SMTP over TLS) via the default port 465. Connection to the server use TLS from the beginning.
 - Forced SMTPS connection with `PROTOCOL=smtps`. (These are both known as Implicit TLS.)
 This is due to protections imposed by the Go internal libraries against STRIPTLS attacks.
@@ -23,7 +23,7 @@ In order to get file rendering through external binaries, their associated packa
 If you're using a Docker image, your `Dockerfile` should contain something along this lines:

 ```docker
-FROM docker.io/gitea/gitea:@dockerVersion@
+FROM docker.gitea.com/gitea:@dockerVersion@
 [...]

 COPY custom/app.ini /data/gitea/conf/app.ini
@@ -14,6 +14,7 @@ aliases:
 2. Make the reverse-proxy pass `https://git.example.com/foo` to `http://gitea:3000/foo`.
 3. Make sure the reverse-proxy does not decode the URI. The request `https://git.example.com/a%2Fb` should be passed as `http://gitea:3000/a%2Fb`.
 4. Make sure `Host` and `X-Fowarded-Proto` headers are correctly passed to Gitea to make Gitea see the real URL being visited.
+5. Make sure your webserver has a certificate, including all intermediate and RootCA certificates, for `git clone` and `git pull` to work. 

 ### Use a sub-path

@@ -149,6 +150,20 @@ server {
 }
 ```

+## Nginx Proxy Manager
+
+If you are using Nginx Proxy Manager to serve your Gitea instance it differs slighly from the raw Nginx.
+
+It is [adding some directives](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/master/docker/rootfs/etc/nginx/conf.d/include/proxy.conf) for a custom location by default, so you have to skip these from the above mentioned Nginx config. Otherwise Nginx will produce `400 bad request` error due to duplicated directives (`proxy_set_header Host $host` is the particularly problematic one).
+
+So while creating the `/` Custom location, just add the following lines to it's configuration:
+
+```nginx
+client_max_body_size 512M;
+proxy_set_header Connection $http_connection;
+proxy_set_header Upgrade $http_upgrade;
+```
+
 ## Apache HTTPD

 If you want Apache HTTPD to serve your Gitea instance, you can add the following to your Apache HTTPD configuration (usually located at `/etc/apache2/httpd.conf` in Ubuntu):
@@ -6,12 +6,14 @@ aliases:
  - /en-us/signing
 ---

-# GPG Commit Signatures
+# GPG/SSH Commit Signatures

-Gitea will verify GPG commit signatures in the provided tree by
+Gitea will verify gpg/ssh commit signatures in the provided tree by
 checking if the commits are signed by a key within the Gitea database,
 or if the commit matches the default key for Git.

+Additionally Gitea will verify commits signed by ssh keys, which public keys are part of [`TRUSTED_SSH_KEYS`](#general-configuration).
+
 Keys are not checked to determine if they have expired or revoked.
 Keys are also not checked with keyservers.

@@ -46,6 +48,11 @@ for GPG - in particular it is probably advisable to only install a
 signing secret subkey without the master signing and certifying secret
 key.

+## Installing and generating a SSH key for Gitea
+
+You can run `ssh-keygen -t ed25519 -f gitea-signing-key` to generate the private/public keypair for commit signing without any password. Usually you would store the key next to the gitea configuration, then point `SIGNING_KEY` to the generated public key `/path/to/gitea-signing-key.pub`. Gitea generates all its commits using the server `git` command at present - and therefore the server `ssh-keygen` will be used for
+signing (if configured.)
+
 ## General Configuration

 Gitea's configuration for signing can be found with the
@@ -65,16 +72,41 @@ MERGES = pubkey, twofa, basesigned, commitssigned
 ...
 ```

+---
+
+For SSH commit signing, you need to specify the `SIGNING_FORMAT` to `ssh` instead of the default `openpgp`. `SIGNING_NAME` and `SIGNING_EMAIL` are required for verifing the signatures.
+
+This looks like this:
+
+```ini
+...
+[repository.signing]
+SIGNING_KEY = /path/to/gitea-signing-key.pub
+SIGNING_NAME =
+SIGNING_EMAIL =
+SIGNING_FORMAT = ssh
+INITIAL_COMMIT = always
+CRUD_ACTIONS = pubkey, twofa, parentsigned
+WIKI = never
+MERGES = pubkey, twofa, basesigned, commitssigned
+...
+```
+
+- `/path/to/gitea-signing-key` is expected to be the private key for `/path/to/gitea-signing-key.pub` [see here how to generate a new ssh keypair](#installing-and-generating-a-ssh-key-for-gitea).
+- `TRUSTED_SSH_KEYS = ssh-<algorithm> <key>` or `TRUSTED_SSH_KEYS = ssh-<algorithm> <key1>, ssh-<algorithm> <key2>` can be used for rotating the global ssh signing key to continue verifying commits signed by the previous keys.
+
 ### `SIGNING_KEY`

 The first option to discuss is the `SIGNING_KEY`. There are three main
 options:

 - `none` - this prevents Gitea from signing any commits
- `default` - Gitea will default to the key configured within `git config`
+- `default` - Gitea will default to the gpg key configured within `git config`
 - `KEYID` - Gitea will sign commits with the gpg key with the ID
  `KEYID`. In this case you should provide a `SIGNING_NAME` and
  `SIGNING_EMAIL` to be displayed for this key.
+- `/path/to/gitea-signing-key.pub` - Gitea will sign commits with the ssh key without the `.pub` suffix `/path/to/gitea-signing-key`. In this case you should provide a `SIGNING_NAME` and
+  `SIGNING_EMAIL` to be displayed for this key and set `SIGNING_FORMAT` to `ssh`.

 The `default` option will interrogate `git config` for
 `commit.gpgsign` option - if this is set, then it will use the results
@@ -97,6 +129,10 @@ Related home files for git command (like `.gnupg`) should also be put in Gitea's
 If you like to keep the `.gnupg` directory outside of `{[git].HOME_PATH}/`, consider setting the `$GNUPGHOME` environment variable to your preferred location, otherwise Gitea will use the gpg keys only under `{[git].HOME_PATH}/.gnupg`.
 :::

+:::warning
+The default option and repository specific signing keys are not supported for ssh keys
+:::
+
 ### `INITIAL_COMMIT`

 This option determines whether Gitea should sign the initial commit
@@ -168,3 +204,9 @@ In cases where there is a repository specific key this can be obtained from:
 ```sh
 /api/v1/repos/:username/:reponame/signing-key.gpg
 ```
+
+For ssh commit signing the default ssh public key can be obtained via the API at:
+
+```sh
+/api/v1/signing-key.pub
+```
@@ -35,8 +35,10 @@ Note that `/users/:name/tokens` is a special endpoint and requires you
 to authenticate using `BasicAuth` and a password, as follows:

 ```sh
-$ curl -H "Content-Type: application/json" -d '{"name":"test"}' -u username:password https://gitea.your.host/api/v1/users/<username>/tokens
-{"id":1,"name":"test","sha1":"9fcb1158165773dd010fca5f0cf7174316c3e37d","token_last_eight":"16c3e37d"}
+$ curl -H "Content-Type: application/json" \
+-d '{"name":"test_token","scopes":["read:activitypub","read:issue", "write:misc", "read:notification", "read:organization", "read:package", "read:repository", "read:user"]}' \
+-u 'username:password' "https://gitea.your.host/api/v1/users/{username}/tokens"
+{"id":1,"name":"test_token","sha1":"9fcb1158165773dd010fca5f0cf7174316c3e37d","token_last_eight":"16c3e37d"}
 ```

 The ``sha1`` (the token) is only returned once and is not stored in
@@ -80,6 +80,7 @@ The approval page displayed to the user shows the list of scopes requested by th
 | OpenID Connect Discovery | `/.well-known/openid-configuration` |
 | Authorization Endpoint   | `/login/oauth/authorize`            |
 | Access Token Endpoint    | `/login/oauth/access_token`         |
+| Token Introspection Endpoint | `/login/oauth/introspect`           |
 | OpenID Connect UserInfo  | `/login/oauth/userinfo`             |
 | JSON Web Key Set         | `/login/oauth/keys`                 |

@@ -330,9 +330,9 @@ It is highly recommended to back-up your database before running these commands.

 - Add your (bare) repositories to the correct spot for your configuration (`repository.ROOT`), ensuring they are in the correct layout `<REPO_ROOT>/[user]/[repo].git`.
  - **Note:** the directory names must be lowercase.
-  - You can also check `<ROOT_URL>/admin/config` for the repository root path.
+  - You can also check `<ROOT_URL>/-/admin/config` for the repository root path.
 - Ensure that the user/org exists that you want to adopt repositories for.
- As an admin, go to `<ROOT_URL>/admin/repos/unadopted` and search.
+- As an admin, go to `<ROOT_URL>/-/admin/repos/unadopted` and search.
  - Users can also be given similar permissions via config [`ALLOW_ADOPTION_OF_UNADOPTED_REPOSITORIES`](../administration/config-cheat-sheet.md#repository-repository).
 - If the above steps are done correctly, you should be able to select repositories to adopt.
  - If no repositories are found, enable [debug logging](../administration/config-cheat-sheet.md#repository-repository) to check for any specific errors.
@@ -13,7 +13,7 @@ Gitea was originally forked from [Gogs](https://gogs.io) and almost all the code

 :::warning

-Gitea does not sent or cherry-picked commits from upstream, so there is no guarantee it will work if you upgrade from Gogs to Gitea. The recommended method is to migrate repositories from Gogs to Gitea.
+Gitea does not send commits to upstream or cherry-pick commits from it, so there is no guarantee it will work if you upgrade from Gogs to Gitea. The recommended method is to migrate repositories from Gogs to Gitea.

 :::

@@ -31,11 +31,11 @@ You can try it out using [the online demo](https://demo.gitea.com).

 - **Code Hosting**

-  Gitea supports creating and managing repositories, browsing commit history and code files, reviewing and merging code submissions, managing collaborators, handling branches, and more. It also supports many common Git features such as tags, Cherry-pick, hooks, integrated collaboration tools, and more.
+  Gitea supports creating and managing repositories, browsing commit history and code files, reviewing and merging code submissions, managing collaborators, handling branches, and more. It also supports many common Git features such as tags, cherry-picking, hooks, integrated collaboration tools, and more.

 - **Lightweight and Fast**

-  One of Gitea's design goals is to be lightweight and fast in response. Unlike some large code hosting platforms, it remains lean, performs well in terms of speed, and is suitable for resource-limited server environments. Due to its lightweight design, Gitea has relatively low resource consumption and performs well in resource-constrained environments.
+  One of Gitea's design goals is to be lightweight and fast in response. Unlike some large code hosting platforms, it remains lean, performs well in terms of speed, and is suitable for resource-limited server environments.

 - **Easy Deployment and Maintenance**

@@ -105,6 +105,6 @@ For more detailed information, please refer to: https://docs.gitea.com/installat
  - [github.com/mattn/go-sqlite3](https://github.com/mattn/go-sqlite3)
  - [github.com/denisenkom/go-mssqldb](https://github.com/denisenkom/go-mssqldb)

-## Integrated support
+## Integrated Support

 Please visit [Awesome Gitea](https://gitea.com/gitea/awesome-gitea/) to get more third-party integrated support
@@ -24,9 +24,10 @@ All steps below requires that the database engine of your choice is installed on

 ## MySQL/MariaDB

-1. For remote database setup, you will need to make MySQL listen to your IP address. Edit `bind-address` option on `/etc/mysql/my.cnf` on database instance to:
+1. For remote database setup, you will need to make MySQL listen to your IP address. Configure the `bind-address` option in `/etc/mysql/my.cnf` on database instance by adding the following lines:

    ```ini
+    [mysqld]
    bind-address = 203.0.113.3
    ```

@@ -46,7 +46,7 @@ Gitea signs all binaries with a [GPG key](https://keys.openpgp.org/search?q=teab
 To validate the binary, download the signature file which ends in `.asc` for the binary you downloaded and use the GPG command line tool.

 ```sh
-gpg --keyserver keys.openpgp.org --recv 7C9E68152594688862D62AF62D9AE806EC1592E2
+gpg --keyserver hkps://keys.openpgp.org --recv 7C9E68152594688862D62AF62D9AE806EC1592E2
 gpg --verify gitea-@[email protected] gitea-@version@-linux-amd64
 ```

@@ -20,7 +20,7 @@ the official [install instructions](https://docs.docker.com/compose/install/).

 ## Basics

-The most simple setup just creates a volume and a network and starts the `docker.io/gitea/gitea:latest-rootless`
+The most simple setup just creates a volume and a network and starts the `docker.gitea.com/gitea:latest-rootless`
 image as a service. Since there is no database available, one can be initialized using SQLite3.

 Create a directory for `data` and `config`:
@@ -38,7 +38,7 @@ version: "2"

 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@-rootless
+    image: docker.gitea.com/gitea:@dockerVersion@-rootless
    restart: always
    volumes:
      - ./data:/var/lib/gitea
@@ -71,7 +71,7 @@ version: "2"

 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@-rootless
+    image: docker.gitea.com/gitea:@dockerVersion@-rootless
    restart: always
    volumes:
      - ./data:/var/lib/gitea
@@ -95,7 +95,7 @@ version: "2"

 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@-rootless
+    image: docker.gitea.com/gitea:@dockerVersion@-rootless
 +    environment:
 +      - GITEA__database__DB_TYPE=mysql
 +      - GITEA__database__HOST=db:3306
@@ -136,7 +136,7 @@ version: "2"

 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@-rootless
+    image: docker.gitea.com/gitea:@dockerVersion@-rootless
    environment:
 +      - GITEA__database__DB_TYPE=postgres
 +      - GITEA__database__HOST=db:5432
@@ -184,7 +184,7 @@ version: "2"
 +
 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@-rootless
+    image: docker.gitea.com/gitea:@dockerVersion@-rootless
    restart: always
    volumes:
 -      - ./data:/var/lib/gitea
@@ -211,7 +211,7 @@ version: "2"

 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@-rootless
+    image: docker.gitea.com/gitea:@dockerVersion@-rootless
    restart: always
 +    user: 1001
    volumes:
@@ -283,7 +283,7 @@ docker-compose up -d
 - Rename folder (inside volume) gitea to custom
 - Edit app.ini if needed
  - Set START_SSH_SERVER = true
- Use image docker.io/gitea/gitea:@dockerVersion@-rootless
+- Use image docker.gitea.com/gitea:@dockerVersion@-rootless

 ## Managing Deployments With Environment Variables

@@ -18,7 +18,7 @@ the official [install instructions](https://docs.docker.com/compose/install/).

 ## Basics

-The most simple setup just creates a volume and a network and starts the `docker.io/gitea/gitea:latest`
+The most simple setup just creates a volume and a network and starts the `docker.gitea.com/gitea:latest`
 image as a service. Since there is no database available, one can be initialized using SQLite3.
 Create a directory like `gitea` and paste the following content into a file named `docker-compose.yml`.
 Note that the volume should be owned by the user/group with the UID/GID specified in the config file.
@@ -34,7 +34,7 @@ networks:

 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@
+    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    environment:
      - USER_UID=1000
@@ -66,7 +66,7 @@ networks:

 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@
+    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    environment:
      - USER_UID=1000
@@ -101,7 +101,7 @@ networks:

 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@
+    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    environment:
      - USER_UID=1000
@@ -152,7 +152,7 @@ networks:

 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@
+    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    environment:
      - USER_UID=1000
@@ -208,7 +208,7 @@ networks:
 +
 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@
+    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    restart: always
    networks:
@@ -266,6 +266,8 @@ files; for named volumes, this is done through another container or by direct ac
 `/var/lib/docker/volumes/gitea_gitea/_data`. The configuration file will be saved at
 `/data/gitea/conf/app.ini` after the installation.

+Example: Analogous to the non-docker-installation customization linked above, you can create a `/public` folder within `/data/gitea` and place your custom `robots.txt` there which will then be served normally.
+
 ## Upgrading

 :::warning
@@ -316,8 +318,8 @@ Gitea will generate new secrets/tokens for every new installation automatically
 The following commands will output a new `SECRET_KEY` and `INTERNAL_TOKEN` to `stdout`, which you can then place in your environment variables.

 ```bash
-docker run -it --rm docker.io/gitea/gitea:1 gitea generate secret SECRET_KEY
-docker run -it --rm docker.io/gitea/gitea:1 gitea generate secret INTERNAL_TOKEN
+docker run -it --rm docker.gitea.com/gitea:1 gitea generate secret SECRET_KEY
+docker run -it --rm docker.gitea.com/gitea:1 gitea generate secret INTERNAL_TOKEN
 ```

 ```yaml
@@ -331,7 +333,7 @@ services:

 ## SSH Container Passthrough

-Since SSH is running inside the container, SSH needs to be passed through from the host to the container if SSH support is desired. One option would be to run the container SSH on a non-standard port (or moving the host port to a non-standard port). Another option which might be more straightforward is for Gitea users to ssh to a Gitea user on the host which will then relay those connections to the docker.
+Since SSH is running inside the container, SSH needs to be passed through from the host to the container if SSH support is desired. One option would be to run the container SSH on a non-standard port (or moving the host port to a non-standard port). Another option which might be more straightforward is for Gitea users to ssh to a Gitea user on the host which will then relay those connections to the docker. Alternatively, if the host machine has more than one IP address, the host can listen on one and Gitea on another.

 ### Understanding SSH access to Gitea (without passthrough)

@@ -384,7 +386,7 @@ In this option, the idea is that the host simply uses the `authorized_keys` that

 - Please note depending on the local version of ssh you may want to consider using `-t ecdsa` here.

- `/home/git/.ssh/authorized_keys` on the host now needs to be modified. It needs to act in the same way as `authorized_keys` within the Gitea container. Therefore add the public key of the key you created above ("Gitea Host Key") to `~/git/.ssh/authorized_keys`. As an administrative user on the host run:
+- `/home/git/.ssh/authorized_keys` on the host now needs to be modified. It needs to act in the same way as `authorized_keys` within the Gitea container. Therefore add the public key of the key you created above ("Gitea Host Key") to `/home/git/.ssh/authorized_keys`. As an administrative user on the host run:

  ```bash
  sudo -u git cat /home/git/.ssh/id_rsa.pub | sudo -u git tee -a /home/git/.ssh/authorized_keys
@@ -642,3 +644,7 @@ If you try to login as the `git` user on the host in future you will `ssh` direc
 Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.

 SSHing shims could be created similarly to above.
+
+### SSH with multiple IP addresses
+This assumes that the host machine has more than one reachable IP address: `192.168.1.1` (host) `192.168.1.2` (gitea)
+On the host machine, configure SSHD in `/etc/ssh/sshd_config` to listen on one IP address `ListenAddress 192.168.1.1`. In the compose file the SSH port forwarding then needs to be changed to `"192.168.1.2:22:22"`. The port forwarding needs to be adjusted similarily for all other forwarded ports to avoid problems with DNS.
@@ -48,7 +48,7 @@ Note that the repository may still use instance-level or organization-level runn

 Before register the runner and run it, you need a registration token. The level of the runner determines where to obtain the registration token.

- Instance level: The admin settings page, like `<your_gitea.com>/admin/actions/runners`.
+- Instance level: The admin settings page, like `<your_gitea.com>/-/admin/actions/runners`.
 - Organization level: The organization settings page, like `<your_gitea.com>/<org>/settings/actions/runners`.
 - Repository level: The repository settings page, like `<your_gitea.com>/<owner>/<repo>/settings/actions/runners`.

@@ -128,6 +128,30 @@ If this file is missing or corrupted, you can simply remove it and register agai
 If you want to store the registration information in another place, you can specify it in the configuration file,
 and don't forget to specify the `--config` option.

+#### Ephemeral Runners
+
+Ephemeral runners provide a security hardening mechanism for enabling organization- or instance-wide runners without requiring full user trust. Once a job is assigned within a spot VM or container, the runner's exposed credentials are automatically revoked—blocking it from polling further jobs before any untrusted code runs, while still allowing it to report progress until completion by either Gitea or the runner.
+
+act_runner **0.2.12+** required.
+
+The updated commands for registering the runner as ephemeral are listed below. Refer to the previous section for detailed information on registering the act_runner.
+
+```bash
+./act_runner register --ephemeral
+```
+
+```bash
+./act_runner --config config.yaml register --ephemeral
+```
+
+```bash
+./act_runner register --no-interactive --ephemeral --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_labels>
+```
+
+The runner must be registered each time it is intended to receive a job. After completing the single job it is designed to execute, the runner terminates.
+
+To automate the registration and startup of new runners when a job is queued, use the `workflow_job` webhook.
+
 ### Start the runner in command line

 After you have registered the runner, you can run it by running the following command:
@@ -210,7 +234,7 @@ Mac uses `launchd` in place of systemd for registering daemon processes. By defa
    <dict>
        <key>PATH</key>
        <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
-        <key>HOME></key>
+        <key>HOME</key>
        <string>/var/lib/act_runner</string>
    </dict>
    <key>UserName</key>
@@ -297,6 +321,36 @@ It is because the act runner will run jobs in docker containers, so it needs to
 As mentioned, you can remove it if you want to run jobs in the host directly.
 To be clear, the "host" actually means the container which is running the act runner now, instead of the host machine.

+---
+
+To enable ephemeral runners, set the environment variable `GITEA_RUNNER_EPHEMERAL=1` in the runner image. This setup doesn't use a `/data` volume because the credentials are single-use and not intended to be reused. You can find more details about this mode under [Ephemeral runners](#ephemeral-runners).
+
+```bash
+docker run \
+    -e GITEA_INSTANCE_URL=<instance_url> \
+    -e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \
+    -e GITEA_RUNNER_EPHEMERAL=1 \
+    -e GITEA_RUNNER_NAME=<runner_name> \
+    --name my_runner \
+    -d docker.io/gitea/act_runner:nightly
+```
+
+```bash
+docker run \
+    -v $PWD/config.yaml:/config.yaml \
+    -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_EPHEMERAL=1 \
+    -e GITEA_RUNNER_NAME=<runner_name> \
+    -e GITEA_RUNNER_LABELS=<runner_labels> \
+    --name my_runner \
+    -d docker.io/gitea/act_runner:nightly
+```
+
+Mounting the host's Docker socket using `/var/run/docker.sock:/var/run/docker.sock` introduces a potential security vulnerability. If a job can access this socket, the reusable `GITEA_RUNNER_REGISTRATION_TOKEN` could be exposed through Docker inspect data.
+
 ### Start the runner using docker compose

 You could also set up the runner using the following `docker-compose.yml`:
@@ -320,7 +374,30 @@ services:

 When using docker, there is no requirement to enter the container and manually run `./act_runner daemon` command as shown below. Once the container has been started successfully, it will show up as an active runner in your Gitea instance.

-## Advantage Configurations
+---
+
+To enable ephemeral runners, set the environment variable `GITEA_RUNNER_EPHEMERAL=1` in the runner image. This setup doesn't use a `/data` volume because the credentials are single-use and not intended to be reused. You can find more details about this mode under [Ephemeral runners](#ephemeral-runners).
+
+```yml
+version: "3.8"
+services:
+  runner:
+    image: docker.io/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}"
+      GITEA_RUNNER_EPHEMERAL: "1"
+    volumes:
+      - ./config.yaml:/config.yaml
+      - /var/run/docker.sock:/var/run/docker.sock
+```
+
+Mounting the host's Docker socket using `/var/run/docker.sock:/var/run/docker.sock` introduces a potential security vulnerability. If a job can access this socket, the reusable `GITEA_RUNNER_REGISTRATION_TOKEN` could be exposed through Docker inspect data.
+
+## Advanced Configurations

 ### Configuring cache when starting a Runner using docker image

@@ -16,7 +16,7 @@ It is designed to be compatible with [GitHub Actions workflow badge](https://doc
 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}
+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.
@@ -24,3 +24,4 @@ https://your-gitea-instance.com/{owner}/{repo}/actions/workflows/{workflow_file}
 - `{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`.
@@ -55,6 +55,23 @@ If you want to give more permissions to the runner, allowing it to access more p
 Refined permission control to Actions is a complicated job.
 In the future, we will add more options to Gitea to make it more configurable, such as allowing more write access to repositories or read access to all repositories in the same organization.

+## Which operating systems are supported by act runner?
+
+We released official binaries for Linux, macOS, and Windows.
+While other operating systems are theoretically supported if it is supported by golang and docker(docker mode enabled).
+
+One thing to note is that if you choose to run jobs directly on the host instead of in job containers, the environmental differences between operating systems may cause unexpected failures.
+
+For example, bash is not available on Windows in most cases, while act tries to use bash to run scripts by default.
+Therefore, you need to specify `powershell` as the default shell in your workflow file, see [defaults.run](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrun).
+
+
+```yaml
+defaults:
+  run:
+    shell: powershell
+```
+
 ## How to avoid being hacked?

 There are two types of possible attacks: unknown runner stealing the code or secrets from your repository, or malicious scripts controlling your runner.
@@ -72,22 +89,6 @@ Here's how we do it on [gitea.com](http://gitea.com/):
 - To run actions for fork pull requests, approval is required. See [#22803](https://github.com/go-gitea/gitea/pull/22803).
 - If someone registers their own runner for their repository or organization on [gitea.com](http://gitea.com/), we have no objections and will just not use it in our org. However, they should take care to ensure that the runner is not used by other users they do not know.

-## Which operating systems are supported by act runner?
-
-It works well on Linux, macOS, and Windows.
-While other operating systems are theoretically supported, they require further testing.
-
-One thing to note is that if you choose to run jobs directly on the host instead of in job containers, the environmental differences between operating systems may cause unexpected failures.
-
-For example, bash is not available on Windows in most cases, while act tries to use bash to run scripts by default.
-Therefore, you need to specify `powershell` as the default shell in your workflow file, see [defaults.run](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrun).
-
-```yaml
-defaults:
-  run:
-    shell: powershell
-```
-
 ## Why choose GitHub Actions? Why not something compatible with GitLab CI/CD?

 [@lunny](https://gitea.com/lunny) has explained this in the [issue to implement actions](https://github.com/go-gitea/gitea/issues/13539).
@@ -100,7 +101,7 @@ It is exciting to be able to reuse them.

 This is valid syntax.
 It means that it should run on runners that have both the `label_a` **and** `label_b` labels, see [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on).
-Unfortunately, act runner does not work this way.
+Unfortunately, act runner does not work this way until v0.2.11.
 As mentioned, we map labels to environments:

 - `ubuntu` → `ubuntu:22.04`
@@ -137,9 +138,10 @@ In the meantime, we suggest that you re-register your runner if you want to chan

 ## Will there be more implementations for Gitea Actions runner?

-Although we would like to provide more options, our limited manpower means that act runner will be the only officially supported runner.
-However, both Gitea and act runner are completely open source, so anyone can create a new/better implementation.
-We support your choice, no matter how you decide.
+Although we would like to provide more options, our limited manpower means that act runner will be the only officially supported runner at the moment.
+
+However, both Gitea and act runner are completely open source under MIT License, so anyone can modify the code to satisfy their requirements.
+
 In case you fork act runner to create your own version: Please contribute the changes back if you can and if you think your changes will help others as well.

 ## What workflow trigger events does Gitea support?
@@ -161,6 +163,8 @@ For events supported only by GitHub, see GitHub's [documentation](https://docs.g
 | pull_request_review_comment | `created`, `edited`                                                                                                      |
 | release                     | `published`, `edited`                                                                                                    |
 | registry_package            | `published`                                                                                                              |
+| workflow_dispatch           | not applicable                                                                                                           |
+| workflow_run                | `requested`, `completed`                                                                                                 |

 > For `pull_request` events, in [GitHub Actions](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request), the `ref` is `refs/pull/:prNumber/merge`, which is a reference to the merge commit preview. However, Gitea has no such reference.
 > Therefore, the `ref` in Gitea Actions is `refs/pull/:prNumber/head`, which points to the head of pull request rather than the preview of the merge commit.
@@ -10,7 +10,7 @@ Starting with Gitea **1.19**, Gitea Actions are available as a built-in CI/CD so

 ## Name

-It is similar and compatible to [GitHub Actions](https://github.com/features/actions), and its name is inspired by it too.
+It is similar and mostly compatible to [GitHub Actions](https://github.com/features/actions), and its name is inspired by it too.
 To avoid confusion, we have clarified the spelling here:

 - "Gitea Actions" (with an "s", both words capitalized) is the name of the Gitea feature.
@@ -22,7 +22,7 @@ To avoid confusion, we have clarified the spelling here:

 Just like other CI/CD solutions, Gitea doesn't run the jobs itself, but delegates the jobs to runners.
 The runner of Gitea Actions is called [act runner](https://gitea.com/gitea/act_runner), it is a standalone program and also written in Go.
-It is based on a [fork](https://gitea.com/gitea/act) of [nektos/act](http://github.com/nektos/act).
+An important part of the application comes from a [fork](https://gitea.com/gitea/act) of [nektos/act](http://github.com/nektos/act).

 Because the runner is deployed independently, there could be potential security issues.
 To avoid them, please follow two simple rules:
@@ -35,8 +35,4 @@ However, for public Gitea instances, such as [gitea.com](https://gitea.com), the

 ## Status

-Gitea Actions is still under development, so there may be some bugs and missing features.
-And breaking changes may be made before it's stable (v1.20 or later).
-
-If the situation changes, we will update it here.
-So please refer to the content here when you find outdated articles elsewhere.
+Gitea Actions is stable enough for production usage and we use Gitea Actions in all the repositories in https://gitea.com/gitea.
@@ -55,7 +55,7 @@ If you are unsure which address to use, the LAN address is usually the right cho
 Each token can be used to create multiple runners, until it is replaced with a new token using the reset link.
 You can obtain different levels of 'tokens' from the following places to create the corresponding level of 'runners':

- Instance level: The admin settings page, like `<your_gitea.com>/admin/actions/runners`.
+- Instance level: The admin settings page, like `<your_gitea.com>/-/admin/actions/runners`.
 - Organization level: The organization settings page, like `<your_gitea.com>/<org>/settings/actions/runners`.
 - Repository level: The repository settings page, like `<your_gitea.com>/<owner>/<repo>/settings/actions/runners`.

@@ -115,7 +115,7 @@ jobs:

 :::warning

-Certain actions may not function correctly within SHA256 repositories. This includes [actions/checkout](https://github.com/actions/checkout/issues/1843).
+Certain actions may not function correctly within SHA256 repositories or when Gitea runs on subpath. This includes [actions/checkout](https://github.com/actions/checkout/issues/1843).

 :::

@@ -0,0 +1,125 @@
+---
+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
+```
+````
+
+## Frontmatter
+
+Gitea supports frontmatter and Table of Contents (TOC) rendering. By default, frontmatter rendering is enabled, and TOC rendering is disabled.
+
+### Enabling TOC rendering
+
+To enable TOC rendering for a markdown file, add `include_toc: true` to its frontmatter section.
+
+### Disabling frontmatter
+
+To disable frontmatter rendering for a markdown file, add `gitea: none` to its frontmatter section.
+
+### Example
+
+```yaml
+---
+include_toc: true
+gitea: none
+---
+```
+
+Then, when you preview this markdown file in Gitea, the frontmatter section will not be rendered, and a Table of Contents will be generated at the top of the content.
@@ -5,7 +5,6 @@ sidebar_position: 110

 aliases:
  - /zh-cn/adding-legal-pages
-
 ---

 # 添加法律页面
@@ -27,9 +27,11 @@ aliases:
  - 例如: LDAP `389`/ LDAPs `636`

 - 安全协议 (可选)
+
  - 连接 LDAP 服务器时是否使用 TLS 协议。

 - 管理员过滤规则 (可选)
+
  - 一个 LDAP 过滤器，用于指定哪些用户应该被赋予管理员特权。如果用户帐户符合过滤器条件，则该用户将被授予管理员权限。
  - 示例:`(objectClass=adminAccount)`
  - 适用于 Microsoft Active Directory（AD）的示例:`memberOf=CN=admin-group,OU=example,DC=example,DC=org`
@@ -45,7 +47,9 @@ aliases:

  - 用户 LDAP 记录中包含用户名字的属性。将用于填充他们的账户信息。
  - 示例:givenName
+
 - 姓氏属性（可选）
+
  - 用户 LDAP 记录中包含用户姓氏的属性。将用于填充他们的账户信息。
  - 示例:`sn`

@@ -83,7 +87,7 @@ aliases:
    但您可以在 app.ini 文件中进行更改。
    有关此部分的详细说明，请参阅[sample
    app.ini](https://github.com/go-gitea/gitea/blob/main/custom/conf/app.example.ini)
-    的_cron.sync_external_users_ 部分的注释。前面提到的_User Search Base_和_User Filter_
+    的*cron.sync_external_users* 部分的注释。前面提到的*User Search Base*和*User Filter*
    设置将限制哪些用户可以使用 Gitea 以及哪些用户将被同步。
    在初始运行任务时，将根据给定的设置创建所有与 LDAP 匹配的用户，因此在使用大型企业 LDAP 目录时需要小心。

@@ -113,6 +117,7 @@ aliases:
 使用以下字段:

 - 群组搜索基础 DN(可选)
+
  - 组使用的 LDAP DN。
  - 示例: `ou=group,dc=mydomain,dc=com`

@@ -156,7 +161,8 @@ PAM提供了一种机制，通过对用户进行PAM认证来自动将其添加
 **Note**: PAM 支持通过[build-time flags](installation/from-source.md#build)添加,
 而官方提供的二进制文件通常不会默认启用此功能。PAM 需要确保系统上有必要的 libpam 动态库，并且编译器可以访问必要的 PAM 开发头文件。

-[^1]: 例如，在Debian "Bullseye"上使用标准Linux登录，可以使用`common-session-noninteractive`。这个值对于其他版本的Debian，
+[^1]:
+    例如，在 Debian "Bullseye"上使用标准 Linux 登录，可以使用`common-session-noninteractive`。这个值对于其他版本的 Debian，
    包括 Ubuntu 和 Mint，可能也是有效的，请查阅您所使用发行版的文档以确认。

 [^2]: **PAM 的必选项** 请注意:在上面的示例中，用户将作为`gituser`而不是`[email protected]`登录到 Gitea 的 Web 界面。
@@ -166,9 +172,11 @@ PAM提供了一种机制，通过对用户进行PAM认证来自动将其添加
 此选项允许 Gitea 以 Gitea 用户身份登录 SMTP 主机。请设置以下字段:

 - 身份验证名称 **(必选)**
+
  - 分配给新授权方法的名称

 - SMTP 验证类型 **(必选)**
+
  - 用于连接 SMTP 主机的验证类型，plain 或 login

 - 主机名 **(必选)**
@@ -5,7 +5,6 @@ sidebar_position: 11

 aliases:
  - /zh-cn/backup-and-restore
-
 ---

 # 备份与恢复
@@ -33,12 +32,12 @@ Gitea 包括数据库、文件和 Git 仓库，当它被使用时所有这些都

 最后生成的 `gitea-dump-1482906742.zip` 文件将会包含如下内容：

-* `app.ini` - 如果原先存储在默认的 custom/ 目录之外，则是配置文件的可选副本
-* `custom/` - 所有保存在 `custom/` 目录下的配置和自定义的文件。
-* `data/` - 数据目录（APP_DATA_PATH），如果使用文件会话，则不包括会话。该目录包括 `attachments`、`avatars`、`lfs`、`indexers`、如果使用 SQLite 则包括 SQLite 文件。
-* `repos/` - 仓库目录的完整副本。
-* `gitea-db.sql` - 数据库dump出来的 SQL。
-* `log/` - Logs文件，如果用作迁移不是必须的。
+- `app.ini` - 如果原先存储在默认的 custom/ 目录之外，则是配置文件的可选副本
+- `custom/` - 所有保存在 `custom/` 目录下的配置和自定义的文件。
+- `data/` - 数据目录（APP_DATA_PATH），如果使用文件会话，则不包括会话。该目录包括 `attachments`、`avatars`、`lfs`、`indexers`、如果使用 SQLite 则包括 SQLite 文件。
+- `repos/` - 仓库目录的完整副本。
+- `gitea-db.sql` - 数据库 dump 出来的 SQL。
+- `log/` - Logs 文件，如果用作迁移不是必须的。

 中间备份文件将会在临时目录进行创建，如果您要重新指定临时目录，可以用 `--tempdir` 参数，或者用 `TMPDIR` 环境变量。

@@ -48,7 +47,7 @@ Gitea 包括数据库、文件和 Git 仓库，当它被使用时所有这些都

 ```sh
 # mysql
-mysqldump -u$USER -p$PASS --database $DATABASE > gitea-db.sql
+mysqldump -u$USER -p$PASS --databases $DATABASE > gitea-db.sql
 # postgres
 pg_dump -U $USER $DATABASE > gitea-db.sql
 ```
@@ -5,7 +5,6 @@ sidebar_position: 20

 aliases:
  - /zh-cn/cmd-embedded
-
 ---

 # 嵌入资源提取工具
@@ -5,7 +5,6 @@ sidebar_position: 1

 aliases:
  - /zh-cn/command-line
-
 ---

 # 命令行
@@ -5,7 +5,6 @@ sidebar_position: 30

 aliases:
  - /zh-cn/config-cheat-sheet
-
 ---

 # 配置说明
@@ -22,14 +21,12 @@ aliases:

 包含`#`或者`;`的变量必须使用引号( `` ` `` 或者 `"` )包裹，否则会被解析为注释。

-
 本文档使用以下约定：

-* `[section].FOO_BAR` 或 `[section]FOO_BAR`: 一个位于 INI 文件 `[section]` 段中的配置项。
-* `FooBar`: 这是一个 Gitea 内部变量，不是一个配置项，仅用于描述相关逻辑。
-* `$FOO_BAR`: 这是一个环境变量，Gitea 可能会使用它的值，但是它不能直接用于配置文件中。
-* `{FOO_BAR}/something` 或 `{FooBar}/something`: 这个值会默认使用配置项 `FOO_BAR` 或者内部变量 `FooBar`。
-
+- `[section].FOO_BAR` 或 `[section]FOO_BAR`: 一个位于 INI 文件 `[section]` 段中的配置项。
+- `FooBar`: 这是一个 Gitea 内部变量，不是一个配置项，仅用于描述相关逻辑。
+- `$FOO_BAR`: 这是一个环境变量，Gitea 可能会使用它的值，但是它不能直接用于配置文件中。
+- `{FOO_BAR}/something` 或 `{FooBar}/something`: 这个值会默认使用配置项 `FOO_BAR` 或者内部变量 `FooBar`。

 **注意:** 修改完配置文件后，需要重启 Gitea 服务才能生效。

@@ -63,9 +60,9 @@ aliases:
  - 这是指向`app.ini`文件的路径。
  - 在构建时设置的内置值（参见从源代码构建）
  - 否则，默认为 _`CustomPath`_`/conf/app.ini`
-  - 如果上述任何路径是相对路径，则会相对于_`CustomPath`_目录进行处理。
+  - 如果上述任何路径是相对路径，则会相对于*`CustomPath`*目录进行处理。

-此外，还有_`StaticRootPath`_，可以在构建时设置为内置值，否则将默认为 _`AppWorkPath`_。
+此外，还有*`StaticRootPath`*，可以在构建时设置为内置值，否则将默认为 _`AppWorkPath`_。

 ## Overall (`DEFAULT`)

@@ -290,7 +287,11 @@ aliases:
 - `DOMAIN`: **localhost**: 此服务器的域名。
 - `ROOT_URL`: **`{PROTOCOL}://{DOMAIN}:{HTTP_PORT}/`**:
  覆盖自动生成的公共 URL。
-   如果内部URL和外部URL不匹配（例如在Docker中），这很有用。
+  这个选项用于内部 URL 和外部 URL 不匹配的情况（例如 Gitea 运行在反向代理后）。
+- `PUBLIC_URL_DETECTION`: **`legacy`**: 控制如何生成公共 URL。
+   虽然它的默认值是 "legacy"（避免影响老的用户），大多数实例都应当使用 "auto" 行为，尤其是 Gitea 实例需要在容器网络中被访问的场景。
+   - "legacy": 当 "X-Forwarded-Proto" 请求头存在的时候，使用 "Host" 请求头生成公共 URL，否则使用 "ROOT_URL"。
+   - "auto": 总是使用 "Host" 请求头生成公共 URL，如果 "X-Forwarded-Proto" 请求头存在也会使用它。如果没有 "Host" 请求头则使用 "ROOT_URL"。
 - `STATIC_URL_PREFIX`: **_empty_**:
  覆盖此选项以从不同的 URL 请求静态资源。
  这包括 CSS 文件、图片、JS 文件和 Web 字体。
@@ -455,15 +456,15 @@ aliases:
 ## 索引 (`indexer`)

 - `ISSUE_INDEXER_TYPE`: **bleve**: 工单索引类型，当前支持：`bleve`、`db`、`elasticsearch` 或 `meilisearch`。
- `ISSUE_INDEXER_CONN_STR`：**** : 工单索引连接字符串，仅适用于 elasticsearch 和 meilisearch（例如：`http://elastic:password@localhost:9200`）或者（例如：`http://:apikey@localhost:7700`）。
+- `ISSUE_INDEXER_CONN_STR`：\*\*\*\* : 工单索引连接字符串，仅适用于 elasticsearch 和 meilisearch（例如：`http://elastic:password@localhost:9200`）或者（例如：`http://:apikey@localhost:7700`）。
 - `ISSUE_INDEXER_NAME`：**gitea_issues**: 工单索引器名称，在 ISSUE_INDEXER_TYPE 为 elasticsearch 或 meilisearch 时可用。
- `ISSUE_INDEXER_PATH`：**indexers/issues.bleve**: 用于工单搜索的索引文件；在 ISSUE_INDEXER_TYPE 为 bleve 和 elasticsearch 时可用。相对路径将相对于 _`AppWorkPath`_ 进行绝对路径化。
+- `ISSUE_INDEXER_PATH`：**indexers/issues.bleve**: 用于工单搜索的索引文件；在 ISSUE*INDEXER_TYPE 为 bleve 和 elasticsearch 时可用。相对路径将相对于 *`AppWorkPath`\_ 进行绝对路径化。

 - `REPO_INDEXER_ENABLED`：**false**: 启用代码搜索（占用大量磁盘空间，约为存储库大小的 6 倍）。
 - `REPO_INDEXER_REPO_TYPES`：**sources,forks,mirrors,templates**: 存储库索引器单元。要索引的项目可以是 `sources`、`forks`、`mirrors`、`templates` 或它们的任何组合，用逗号分隔。如果为空，则默认为仅 `sources`，如果要完全禁用，请参见 `REPO_INDEXER_ENABLED`。
 - `REPO_INDEXER_TYPE`：**bleve**: 代码搜索引擎类型，可以为 `bleve` 或者 `elasticsearch`。
 - `REPO_INDEXER_PATH`：**indexers/repos.bleve**: 用于代码搜索的索引文件。
- `REPO_INDEXER_CONN_STR`：****: 代码索引器连接字符串，在 `REPO_INDEXER_TYPE` 为 elasticsearch 时可用。例如：`http://elastic:password@localhost:9200`
+- `REPO_INDEXER_CONN_STR`：\*\*\*\*: 代码索引器连接字符串，在 `REPO_INDEXER_TYPE` 为 elasticsearch 时可用。例如：`http://elastic:password@localhost:9200`
 - `REPO_INDEXER_NAME`：**gitea_codes**: 代码索引器名称，在 `REPO_INDEXER_TYPE` 为 elasticsearch 时可用。

 - `REPO_INDEXER_INCLUDE`：**empty**: 逗号分隔的 glob 模式列表（参见 [https://github.com/gobwas/glob](https://github.com/gobwas/glob)）以用于**包括**在索引中。使用 `**.txt` 匹配任何具有 .txt 扩展名的文件。空列表表示包括所有文件。
@@ -481,8 +482,8 @@ aliases:
 - `LENGTH`：**100000**: 通道队列阻塞之前的最大队列大小
 - `BATCH_LENGTH`：**20**: 在传递给处理程序之前批处理数据
 - `CONN_STR`：**redis://127.0.0.1:6379/0**: redis 队列类型的连接字符串。对于 `redis-cluster`，使用 `redis+cluster://127.0.0.1:6379/0`。可以使用查询参数来设置选项。类似地，LevelDB 选项也可以使用：**leveldb://relative/path?option=value** 或 **leveldb:///absolute/path?option=value** 进行设置，并将覆盖 `DATADIR`。
- `QUEUE_NAME`：**_queue**: 默认的 redis 和磁盘队列名称的后缀。单独的队列将默认为 **`name`**`QUEUE_NAME`，但可以在特定的 `queue.name` 部分中进行覆盖。
- `SET_NAME`：**_unique**: 将添加到默认的 redis 和磁盘队列 `set` 名称中以用于唯一队列的后缀。单独的队列将默认为 **`name`**`QUEUE_NAME`_`SET_NAME`_，但可以在特定的 `queue.name` 部分中进行覆盖。
+- `QUEUE_NAME`：**\_queue**: 默认的 redis 和磁盘队列名称的后缀。单独的队列将默认为 **`name`**`QUEUE_NAME`，但可以在特定的 `queue.name` 部分中进行覆盖。
+- `SET_NAME`：**\_unique**: 将添加到默认的 redis 和磁盘队列 `set` 名称中以用于唯一队列的后缀。单独的队列将默认为 **`name`**`QUEUE_NAME`_`SET_NAME`_，但可以在特定的 `queue.name` 部分中进行覆盖。
 - `MAX_WORKERS`：**(dynamic)**: 队列的最大工作协程数。默认值为 "CpuNum/2"，限制在 1 到 10 之间。

 Gitea 创建以下非唯一队列：
@@ -516,7 +517,7 @@ Gitea 创建以下非唯一队列：
 - `SECRET_KEY`: **\<每次安装时随机生成\>**: 全局服务器安全密钥。这个密钥非常重要，如果丢失将无法解密加密的数据（例如 2FA）。
 - `SECRET_KEY_URI`: **_empty_**: 与定义 `SECRET_KEY` 不同，此选项可用于使用存储在文件中的密钥（示例值：`file:/etc/gitea/secret_key`）。它不应该像 `SECRET_KEY` 一样容易丢失。
 - `LOGIN_REMEMBER_DAYS`: **31**: 在要求重新登录之前，记住用户的登录状态多长时间（以天为单位）。
- `COOKIE_REMEMBER_NAME`: **gitea\_incredible**: 保存自动登录信息的 Cookie 名称。
+- `COOKIE_REMEMBER_NAME`: **gitea_incredible**: 保存自动登录信息的 Cookie 名称。
 - `REVERSE_PROXY_AUTHENTICATION_USER`: **X-WEBAUTH-USER**: 反向代理认证的 HTTP 头部名称，用于提供用户信息。
 - `REVERSE_PROXY_AUTHENTICATION_EMAIL`: **X-WEBAUTH-EMAIL**: 反向代理认证的 HTTP 头部名称，用于提供邮箱信息。
 - `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`: **X-WEBAUTH-FULLNAME**: 反向代理认证的 HTTP 头部名称，用于提供全名信息。
@@ -571,13 +572,13 @@ Gitea 创建以下非唯一队列：
 ## OpenID (`openid`)

 - `ENABLE_OPENID_SIGNIN`: **true**: 允许通过 OpenID 进行身份验证。
- `ENABLE_OPENID_SIGNUP`: **! DISABLE\_REGISTRATION**: 允许通过OpenID进行注册。
+- `ENABLE_OPENID_SIGNUP`: **! DISABLE_REGISTRATION**: 允许通过 OpenID 进行注册。
 - `WHITELISTED_URIS`: **_empty_**: 如果非空，是一组匹配 OpenID URI 的 POSIX 正则表达式模式，用于允许访问。
 - `BLACKLISTED_URIS`: **_empty_**: 如果非空，是一组匹配 OpenID URI 的 POSIX 正则表达式模式，用于阻止访问。

 ## OAuth2 Client (`oauth2_client`)

- `REGISTER_EMAIL_CONFIRM`: _[service]_ **REGISTER\_EMAIL\_CONFIRM**: 设置此项以启用或禁用OAuth2自动注册的电子邮件确认。（覆盖`[service]`部分的`REGISTER\_EMAIL\_CONFIRM`设置）
+- `REGISTER_EMAIL_CONFIRM`: _[service]_ **REGISTER_EMAIL_CONFIRM**: 设置此项以启用或禁用 OAuth2 自动注册的电子邮件确认。（覆盖`[service]`部分的`REGISTER\_EMAIL\_CONFIRM`设置）
 - `OPENID_CONNECT_SCOPES`: **_empty_**: 附加的 OpenID 连接范围的列表。（`openid`已隐式添加）
 - `ENABLE_AUTO_REGISTRATION`: **false**: 为新的 OAuth2 用户自动创建用户帐户。
 - `USERNAME`: **nickname**: 新 OAuth2 帐户的用户名来源：
@@ -631,7 +632,7 @@ Gitea 创建以下非唯一队列：
 - `DEFAULT_ALLOW_ONLY_CONTRIBUTORS_TO_TRACK_TIME`: **true**: 仅允许具有写权限的用户跟踪时间。
 - `EMAIL_DOMAIN_ALLOWLIST`: **_empty_**: 如果非空，逗号分隔的域名列表，只能用于在此实例上注册，支持通配符。
 - `EMAIL_DOMAIN_BLOCKLIST`: **_empty_**: 如果非空，逗号分隔的域名列表，不能用于在此实例上注册，支持通配符。
- `SHOW_REGISTRATION_BUTTON`: **! DISABLE\_REGISTRATION**: 显示注册按钮
+- `SHOW_REGISTRATION_BUTTON`: **! DISABLE_REGISTRATION**: 显示注册按钮
 - `SHOW_MILESTONES_DASHBOARD_PAGE`: **true** 启用此项以显示里程碑仪表板页面 - 查看所有用户的里程碑
 - `AUTO_WATCH_NEW_REPOS`: **true** 启用此项以在创建新存储库时让所有组织用户观看新存储库
 - `AUTO_WATCH_ON_CHANGES`: **false** 启用此项以在首次提交后使用户观看存储库
@@ -677,7 +678,7 @@ Gitea 创建以下非唯一队列：
 - `SKIP_TLS_VERIFY`: **false**: 允许不安全的证书。
 - `PAGING_NUM`: **10**: 一页中显示的 Webhook 历史事件数量。
 - `PROXY_URL`: **_empty_**: 代理服务器 URL，支持 http://、https://、socks://，留空将遵循环境的 http_proxy/https_proxy 设置。如果未提供，将使用全局代理设置。
- `PROXY_HOSTS`: **_empty_**: 需要代理的主机名的逗号分隔列表。支持通配符模式 (*)；使用 ** 来匹配所有主机。如果未提供，将使用全局代理设置。
+- `PROXY_HOSTS`: **_empty_**: 需要代理的主机名的逗号分隔列表。支持通配符模式 (\*)；使用 \*\* 来匹配所有主机。如果未提供，将使用全局代理设置。

 ## 邮件 (`mailer`)

@@ -752,7 +753,7 @@ Gitea 创建以下非唯一队列：
 - `PROVIDER`: **memory**: 会话存储引擎 \[memory, file, redis, redis-cluster, db, mysql, couchbase, memcache, postgres\]。设置为 `db` 将会重用 `[database]` 的配置信息。
 - `PROVIDER_CONFIG`: **data/sessions**: 对于文件，为根路径；对于 db，为空（将使用数据库配置）；对于其他引擎，为连接字符串。相对路径将根据 _`AppWorkPath`_ 绝对化。
 - `COOKIE_SECURE`: **_empty_**: `true` 或 `false`。启用此选项以强制在所有会话访问中使用 HTTPS。如果没有设置，当 ROOT_URL 是 https 链接的时候默认设置为 true。
- `COOKIE_NAME`: **i\_like\_gitea**: 用于会话 ID 的 cookie 名称。
+- `COOKIE_NAME`: **i_like_gitea**: 用于会话 ID 的 cookie 名称。
 - `GC_INTERVAL_TIME`: **86400**: GC 间隔时间，以秒为单位。
 - `SESSION_LIFE_TIME`: **86400**: 会话生命周期，以秒为单位，默认为 86400（1 天）。
 - `DOMAIN`: **_empty_**: 设置 cookie 的域。
@@ -1094,7 +1095,7 @@ IS_INPUT_FILE = false

 - ENABLED：**false** 设置是否启动渲染器
 - NEED_POSTPROCESS：**true** 设置为**true**以替换链接/SHA1 等。
- FILE_EXTENSIONS：**_empty_** 要由外部命令渲染的文件扩展名列表。多个扩展名需要用逗号分隔。
+- FILE*EXTENSIONS：\*\*\_empty*\*\* 要由外部命令渲染的文件扩展名列表。多个扩展名需要用逗号分隔。
 - RENDER_COMMAND：用于渲染所有匹配的扩展名的外部命令。
 - IS_INPUT_FILE：**false** 输入不是标准输入，而是一个在`RENDER_COMMAND`之后带有文件参数的文件。
 - RENDER_CONTENT_MODE：**sanitized** 内容将如何呈现。
@@ -1333,7 +1334,7 @@ MINIO_BUCKET_LOOKUP_TYPE = auto

 - `PROXY_ENABLED`: **false**: 启用代理，如果为 true，所有通过 HTTP 向外部的请求都将受到影响，如果为 false，即使环境设置了 http_proxy/https_proxy 也不会使用
 - `PROXY_URL`: **_empty_**: 代理服务器地址，支持 http://, https//, socks://，为空则不启用代理而使用环境变量中的 http_proxy/https_proxy
- `PROXY_HOSTS`: **_empty_**: 逗号分隔的多个需要代理的网址，支持 * 号匹配符号， ** 表示匹配所有网站
+- `PROXY_HOSTS`: **_empty_**: 逗号分隔的多个需要代理的网址，支持 \* 号匹配符号， \*\* 表示匹配所有网站

 i.e.

@@ -5,7 +5,6 @@ sidebar_position: 100

 aliases:
  - /zh-cn/customizing-gitea
-
 ---

 # 自定义 Gitea 配置
@@ -5,7 +5,6 @@ sidebar_position: 12

 aliases:
  - /zh-cn/email-setup
-
 ---

 # Email 设置
@@ -5,7 +5,6 @@ sidebar_position: 10

 aliases:
  - /zh-cn/environment-variables
-
 ---

 # 环境变量清单
@@ -20,31 +19,31 @@ GITEA_CUSTOM=/home/gitea/custom ./gitea web

 因为 Gitea 使用 Go 语言编写，因此它使用了一些相关的 Go 的配置参数：

-* `GOOS`
-* `GOARCH`
-* [`GOPATH`](https://go.dev/cmd/go/#hdr-GOPATH_environment_variable)
+- `GOOS`
+- `GOARCH`
+- [`GOPATH`](https://go.dev/cmd/go/#hdr-GOPATH_environment_variable)

 您可以在[官方文档](https://go.dev/cmd/go/#hdr-Environment_variables)中查阅这些配置参数的详细信息。

 ## Gitea 的文件目录

-* `GITEA_WORK_DIR`：工作目录的绝对路径
-* `GITEA_CUSTOM`：默认情况下 Gitea 使用默认目录 `GITEA_WORK_DIR`/custom，您可以使用这个参数来配置 *custom* 目录
-* `GOGS_WORK_DIR`： 已废弃，请使用 `GITEA_WORK_DIR` 替代
-* `GOGS_CUSTOM`： 已废弃，请使用 `GITEA_CUSTOM` 替代
+- `GITEA_WORK_DIR`：工作目录的绝对路径
+- `GITEA_CUSTOM`：默认情况下 Gitea 使用默认目录 `GITEA_WORK_DIR`/custom，您可以使用这个参数来配置 _custom_ 目录
+- `GOGS_WORK_DIR`： 已废弃，请使用 `GITEA_WORK_DIR` 替代
+- `GOGS_CUSTOM`： 已废弃，请使用 `GITEA_CUSTOM` 替代

 ## 操作系统配置

-* `USER`：Gitea 运行时使用的系统用户，它将作为一些 repository 的访问地址的一部分
-* `USERNAME`： 如果没有配置 `USER`， Gitea 将使用 `USERNAME`
-* `HOME`： 用户的 home 目录，在 Windows 中会使用 `USERPROFILE` 环境变量
+- `USER`：Gitea 运行时使用的系统用户，它将作为一些 repository 的访问地址的一部分
+- `USERNAME`： 如果没有配置 `USER`， Gitea 将使用 `USERNAME`
+- `HOME`： 用户的 home 目录，在 Windows 中会使用 `USERPROFILE` 环境变量

 ### 仅限于 Windows 的配置

-* `USERPROFILE`： 用户的主目录，如果未配置则会使用 `HOMEDRIVE` + `HOMEPATH`
-* `HOMEDRIVE`: 用于访问 home 目录的主驱动器路径（C盘）
-* `HOMEPATH`：在指定主驱动器下的 home 目录相对路径
+- `USERPROFILE`： 用户的主目录，如果未配置则会使用 `HOMEDRIVE` + `HOMEPATH`
+- `HOMEDRIVE`: 用于访问 home 目录的主驱动器路径（C 盘）
+- `HOMEPATH`：在指定主驱动器下的 home 目录相对路径

 ## Miscellaneous

-* `SKIP_MINWINSVC`：如果设置为 1，在 Windows 上不会以 service 的形式运行。
+- `SKIP_MINWINSVC`：如果设置为 1，在 Windows 上不会以 service 的形式运行。
@@ -5,7 +5,6 @@ sidebar_position: 60

 aliases:
  - /zh-cn/external-renderers
-
 ---

 # 外部渲染器
@@ -24,7 +23,7 @@ Gitea 通过外部二进制文件支持自定义文件渲染（例如 Jupyter no
 如果您正在使用 Docker 镜像，则您的 `Dockerfile` 应该包含以下内容：

 ```docker
-FROM docker.io/gitea/gitea:@dockerVersion@
+FROM docker.gitea.com/gitea:@dockerVersion@
 [...]

 COPY custom/app.ini /data/gitea/conf/app.ini
@@ -171,7 +170,8 @@ ALLOW_DATA_URI_IMAGES = true

 .markup.XXXXX body {
  color: #444;
-  font-family: Georgia, Palatino, 'Palatino Linotype', Times, 'Times New Roman', serif;
+  font-family: Georgia, Palatino, "Palatino Linotype", Times, "Times New Roman",
+    serif;
  font-size: 12px;
  line-height: 1.7;
  padding: 1em;
@@ -5,7 +5,6 @@ sidebar_position: 16

 aliases:
  - /zh-cn/fail2ban-setup
-
 ---

 # 设置 Fail2ban
@@ -5,7 +5,6 @@ sidebar_position: 12

 aliases:
  - /zh-cn/git-lfs-setup
-
 ---

 # Git LFS 设置
@@ -18,7 +18,7 @@ aliases:
 目前，以下通知事件使用模板：

 | 操作名称   | 用途                                                                   |
-| ----------- | ------------------------------------------------------------------------------------------------------------ |
+| ---------- | ---------------------------------------------------------------------- |
 | `new`      | 创建了新的工单或合并请求。                                             |
 | `comment`  | 在现有工单或合并请求中创建了新的评论。                                 |
 | `close`    | 关闭了工单或合并请求。                                                 |
@@ -75,7 +75,7 @@ custom/templates/mail/pull/comment.tmpl
 _主题_ 和 _邮件正文_ 由 [Golang 的模板引擎](https://go.dev/pkg/text/template/) 解析，并提供了为每个通知组装的 _元数据上下文_。上下文包含以下元素：

 | 名称               | 类型             | 可用性         | 用途                                                                                                                                                                    |
-| -------------------- | ------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ------------------ | ---------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `.FallbackSubject` | string           | 始终可用       | 默认主题行。参见下文。                                                                                                                                                  |
 | `.Subject`         | string           | 仅在正文中可用 | 解析后的 _主题_。                                                                                                                                                       |
 | `.Body`            | string           | 始终可用       | 工单、合并请求或评论的消息，从 Markdown 解析为 HTML 并进行了清理。请勿与 _邮件正文_ 混淆。                                                                              |
@@ -221,11 +221,11 @@ _主题_ 和 _邮件正文_ 由 [Golang的模板引擎](https://go.dev/pkg/text/
 >
 > #### 消息内容
 >
-> \_********************************\_********************************
+> \_******\*\*******\*\*\*\*******\*\*******\_******\*\*******\*\*\*\*******\*\*******
 >
 > Mike, I think we should tone down the blues a little.
 >
-> \_********************************\_********************************
+> \_******\*\*******\*\*\*\*******\*\*******\_******\*\*******\*\*\*\*******\*\*******
 >
 > [在 Gitea 上查看](#)。

@@ -234,7 +234,7 @@ _主题_ 和 _邮件正文_ 由 [Golang的模板引擎](https://go.dev/pkg/text/
 模板系统包含一些函数，可用于进一步处理和格式化消息。以下是其中一些函数的列表：

 | 函数名           | 参数        | 可用于     | 用法                                             |
-|------------------| ----------- | ------------ | ------------------------------ |
+| ---------------- | ----------- | ---------- | ------------------------------------------------ |
 | `AppUrl`         | -           | 任何地方   | Gitea 的 URL                                     |
 | `AppName`        | -           | 任何地方   | 从 `app.ini` 中设置，通常为 "Gitea"              |
 | `AppDomain`      | -           | 任何地方   | Gitea 的主机名                                   |
@@ -245,8 +245,10 @@ _主题_ 和 _邮件正文_ 由 [Golang的模板引擎](https://go.dev/pkg/text/
 这些都是 _函数_，而不是元数据，因此必须按以下方式使用：

 ```html
-像这样使用：         {{SanitizeHTML "Escape<my>text"}}
-或者这样使用：       {{"Escape<my>text" | SanitizeHTML}}
-或者这样使用：       {{AppUrl}}
-但不要像这样使用：   {{.AppUrl}}
+像这样使用： {{SanitizeHTML "Escape<my
+  >text"}} 或者这样使用： {{"Escape<my
+    >text" | SanitizeHTML}} 或者这样使用： {{AppUrl}} 但不要像这样使用：
+    {{.AppUrl}}</my
+  ></my
+>
 ```
@@ -16,10 +16,10 @@ 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/`
+- **CSS 样式**： `web_src/css/`
+- **JavaScript 文件**： `web_src/js/`
+- **Vue 组件**： `web_src/js/components/`
+- **Go HTML 模板**： `templates/`

 ## 通用准则

@@ -54,16 +54,16 @@ Gitea 使用一些补丁使 Fomantic UI 更具可访问性（参见 `aria.md`）

 推荐的实现方式：

-* Vue + Vanilla JS
-* Fomantic-UI（jQuery）
-* htmx （部分页面重新加载其他静态组件）
-* Vanilla JS
+- Vue + Vanilla JS
+- Fomantic-UI（jQuery）
+- htmx （部分页面重新加载其他静态组件）
+- Vanilla JS

 不推荐的实现方式：

-* Vue + Fomantic-UI（jQuery）
-* jQuery + Vanilla JS
-* htmx + 任何其他需要大量 JavaScript 代码或不必要的功能，如 htmx 脚本 (`hx-on`)
+- Vue + Fomantic-UI（jQuery）
+- jQuery + Vanilla JS
+- htmx + 任何其他需要大量 JavaScript 代码或不必要的功能，如 htmx 脚本 (`hx-on`)

 为了保持界面一致，Vue 组件可以使用 Fomantic-UI 的 CSS 类。
 尽管不建议混合使用不同的框架，
@@ -97,31 +97,41 @@ Gitea 使用一些补丁使 Fomantic UI 更具可访问性（参见 `aria.md`）
 禁止使用`dataset`，它的驼峰命名行为使得搜索属性变得困难。
 然而，仍然存在一些特殊情况，因此当前的准则是：

-* 对于旧代码：
-  * 应将`$.data()`重构为`$.attr()`。
-  * 在极少数情况下，可以使用`$.data()`将一些非字符串数据绑定到元素上，但强烈不推荐使用。
+- 对于旧代码：

-* 对于新代码：
-  * 不应使用`node.dataset`，而应使用`node.getAttribute`。
-  * 不要将任何用户数据绑定到 DOM 节点上，使用合适的设计模式描述节点和数据之间的关系。
+  - 应将`$.data()`重构为`$.attr()`。
+  - 在极少数情况下，可以使用`$.data()`将一些非字符串数据绑定到元素上，但强烈不推荐使用。
+
+- 对于新代码：
+  - 不应使用`node.dataset`，而应使用`node.getAttribute`。
+  - 不要将任何用户数据绑定到 DOM 节点上，使用合适的设计模式描述节点和数据之间的关系。

 ### 显示/隐藏元素

-* 推荐在Vue组件中使用`v-if`和`v-show`来显示/隐藏元素。
-* Go 模板代码应使用 `.tw-hidden` 和 `showElem()/hideElem()/toggleElem()` 来显示/隐藏元素，请参阅`.tw-hidden`的注释以获取更多详细信息。
+- 推荐在 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>
+<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>
+<div
+  class="gt-name1 gt-name2{{if .IsFoo}} gt-foo{{end}}"
+  {{if
+  .IsFoo}}
+  data-foo{{end}}
+></div>
 ```

 以使代码更易读。
@@ -19,22 +19,22 @@ aliases:

 ## 重构建议

-* 设计更多关于未来的内容，而不仅仅解决当前问题。
-* 减少模糊性，减少冲突，提高可维护性。
-* 描述重构，例如：
-  * 为什么需要重构。
-  * 如何解决旧问题。
-  * 重构的优点/缺点是什么。
-* 只做必要的更改，尽量保留旧逻辑。
-* 引入一些中间步骤，使重构更容易审查，完整的重构计划可以在几个PR中完成。
-* 如果存在分歧，应该请TOC（技术监督委员会）参与决策。
-* 添加必要的测试以确保重构的正确性。
-* 非错误重构优先在里程碑的开始时进行，这样可以更容易地在发布之前发现问题。
+- 设计更多关于未来的内容，而不仅仅解决当前问题。
+- 减少模糊性，减少冲突，提高可维护性。
+- 描述重构，例如：
+  - 为什么需要重构。
+  - 如何解决旧问题。
+  - 重构的优点/缺点是什么。
+- 只做必要的更改，尽量保留旧逻辑。
+- 引入一些中间步骤，使重构更容易审查，完整的重构计划可以在几个 PR 中完成。
+- 如果存在分歧，应该请 TOC（技术监督委员会）参与决策。
+- 添加必要的测试以确保重构的正确性。
+- 非错误重构优先在里程碑的开始时进行，这样可以更容易地在发布之前发现问题。

 ## 审查和合并建议

-* 重构的PR不应该长时间保持打开状态（通常为7天），应尽快进行审查。
-* 重构的PR应尽快合并，不应被其他PR阻塞。
-* 如果TOC没有异议，重构的PR可以在7天后由一名核心成员（非作者）批准后合并。
-* 如果最终结果良好，容忍一些不完美/临时的步骤。
-* 如果重构是必要的，容忍一些回归错误，并尽快修复错误。
+- 重构的 PR 不应该长时间保持打开状态（通常为 7 天），应尽快进行审查。
+- 重构的 PR 应尽快合并，不应被其他 PR 阻塞。
+- 如果 TOC 没有异议，重构的 PR 可以在 7 天后由一名核心成员（非作者）批准后合并。
+- 如果最终结果良好，容忍一些不完美/临时的步骤。
+- 如果重构是必要的，容忍一些回归错误，并尽快修复错误。
@@ -62,7 +62,7 @@ Make 的这三个发行版都可以在 Windows 上运行：
  - 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 一样。
+  - 要使用 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`。
@@ -34,7 +34,7 @@ Gitea 支持作为 OAuth2 提供者，允许第三方应用程序在用户同意
 Gitea 支持以下令牌范围:

 | 名称                                     | 介绍                                                            |
-| ---- | ----------- |
+| ---------------------------------------- | --------------------------------------------------------------- |
 | **(no scope)**                           | 授予对公共用户配置文件和公共存储库的只读访问权限                |
 | **repo**                                 | 完全控制所有存储库                                              |
 | &nbsp;&nbsp;&nbsp; **repo:status**       | 授予对所有存储库中提交状态的读/写访问权限                       |
@@ -53,18 +53,18 @@ https://github.com/loganinak/MigrateGitlabToGogs
  - 或者包含 Gitea 二进制文件的目录
 - `%(APP_DATA_PATH)`（数据库、索引器等的默认路径）
  - `app.ini`中的`APP_DATA_PATH`
-  - 或者_`AppWorkPath`_`/data`
+  - 或者*`AppWorkPath`*`/data`
 - _`CustomPath`_（自定义模板）
  - `--custom-path`标志
  - 或者环境变量`GITEA_CUSTOM`
  - 或者在构建时设置的内置值
-  - 或者_`AppWorkPath`_`/custom`
+  - 或者*`AppWorkPath`*`/custom`
 - HomeDir
  - Unix：环境变量`HOME`
  - Windows：环境变量`USERPROFILE`，或者环境变量`HOMEDRIVE`+`HOMEPATH`
 - RepoRootPath
  - `app.ini`中\[repository]部分的`ROOT`（如果是绝对路径）
-  - 否则_`AppWorkPath`_`/ROOT`(如果`app.ini`中\[repository]部分的`ROOT`是相对路径）
+  - 否则*`AppWorkPath`*`/ROOT`(如果`app.ini`中\[repository]部分的`ROOT`是相对路径）
  - 默认值为`%(APP_DATA_PATH)/gitea-repositories`
 - INI（配置文件）
  - `--config`标志
@@ -251,12 +251,14 @@ fatal: Could not read from remote repository.
    Git 用户（@ 之前的部分）的名称拼写正确。
  - 确保客户端机器上的公钥和私钥正确无误。
 - 在服务器上：
+
  - 确保存储库存在并且命名正确。
  - 检查系统用户主目录中的 `.ssh` 目录的权限。
  - 验证正确的公钥是否已添加到 `.ssh/authorized_keys` 中。

  尝试在 Gitea 管理面板上运行
  `Rewrite '.ssh/authorized_keys' file (for Gitea SSH keys)`。
+
 - 查看 Gitea 日志。
 - 查看 /var/log/auth（或类似的文件）。
 - 检查存储库的权限。
@@ -328,7 +330,9 @@ Gitea 提供了一个子命令`gitea migrate`来初始化数据库，然后您
 - 使用[管理 CLI 命令](../administration/command-line.md#admin)。

  请注意，大多数命令还需要一个[全局标志](../administration/command-line.md#全局选项)来指向正确的配置。
+
 - 作为**用户**，您可以更改密码...
+
  - 在您的账户的`设置 -> 账户`页面（此方法**需要**您知道当前密码）。
  - 使用`忘记密码`链接。

@@ -14,18 +14,18 @@ aliases:

 _表格中的符号含义:_

-* _✓ - 支持_
+- _✓ - 支持_

-* _⁄ - 部分支持_
+- _⁄ - 部分支持_

-* _✘ - 不支持_
+- _✘ - 不支持_

-* _⚙️ - 由第三方服务或插件支持_
+- _⚙️ - 由第三方服务或插件支持_

 #### 主要特性

 | 特性                             | Gitea                                               | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket      | RhodeCode CE |
-| ------------------------------- | -------------------------------------------------- | ---- | --------- | --------- | --------- | -------------- | ------------ |
+| -------------------------------- | --------------------------------------------------- | ---- | --------- | --------- | --------- | -------------- | ------------ |
 | 开源免费                         | ✓                                                   | ✓    | ✘         | ✓         | ✘         | ✘              | ✓            |
 | 低资源开销 (RAM/CPU)             | ✓                                                   | ✓    | ✘         | ✘         | ✘         | ✘              | ✘            |
 | 支持多种数据库                   | ✓                                                   | ✓    | ✘         | ⁄         | ⁄         | ✓              | ✓            |
@@ -56,7 +56,7 @@ _表格中的符号含义:_
 #### 代码管理

 | 特性                 | Gitea                                               | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE |
-| ------------------------------------ | --------------------------------------------------- | ---- | --------- | --------- | --------- | --------- | ------------ |
+| -------------------- | --------------------------------------------------- | ---- | --------- | --------- | --------- | --------- | ------------ |
 | 仓库主题描述         | ✓                                                   | ✘    | ✓         | ✓         | ✓         | ✘         | ✘            |
 | 仓库内代码搜索       | ✓                                                   | ✘    | ✓         | ✓         | ✓         | ✓         | ✓            |
 | 全局代码搜索         | ✓                                                   | ✘    | ✓         | ✘         | ✓         | ✓         | ✓            |
@@ -39,7 +39,7 @@ Gitea 对打包的二进制文件使用 [GPG密钥](https://keys.openpgp.org/sea
 请根据对应文件名 `.asc` 中包含的校验码检验文件的一致性。

 ```sh
-gpg --keyserver keys.openpgp.org --recv 7C9E68152594688862D62AF62D9AE806EC1592E2
+gpg --keyserver hkps://keys.openpgp.org --recv 7C9E68152594688862D62AF62D9AE806EC1592E2
 gpg --verify gitea-@version@-linux-amd64.asc gitea-@version@-linux-amd64
 ```

@@ -16,7 +16,7 @@ rootless 镜像使用 Gitea 内部 SSH 功能来提供 Git 协议，但不支持

 ## 基础设置

-最简单的设置只需创建一个卷和一个网络，并将 `gitea/gitea:latest-rootless` 镜像作为服务启动。由于没有可用的数据库，可以使用 SQLite3 来初始化一个。
+最简单的设置只需创建一个卷和一个网络，并将 `docker.gitea.com/gitea:latest-rootless` 镜像作为服务启动。由于没有可用的数据库，可以使用 SQLite3 来初始化一个。

 创建一个名为 `data` 和 `config`:

@@ -33,7 +33,7 @@ version: "2"

 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@-rootless
+    image: docker.gitea.com/gitea:@dockerVersion@-rootless
    restart: always
    volumes:
      - ./data:/var/lib/gitea
@@ -64,7 +64,7 @@ version: "2"

 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@-rootless
+    image: docker.gitea.com/gitea:@dockerVersion@-rootless
    restart: always
    volumes:
      - ./data:/var/lib/gitea
@@ -87,7 +87,7 @@ version: "2"

 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@-rootless
+    image: docker.gitea.com/gitea:@dockerVersion@-rootless
 +    environment:
 +      - GITEA__database__DB_TYPE=mysql
 +      - GITEA__database__HOST=db:3306
@@ -127,7 +127,7 @@ version: "2"

 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@-rootless
+    image: docker.gitea.com/gitea:@dockerVersion@-rootless
    environment:
 +      - GITEA__database__DB_TYPE=postgres
 +      - GITEA__database__HOST=db:5432
@@ -172,7 +172,7 @@ version: "2"
 +
 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@-rootless
+    image: docker.gitea.com/gitea:@dockerVersion@-rootless
    restart: always
    volumes:
 -      - ./data:/var/lib/gitea
@@ -199,7 +199,7 @@ version: "2"

 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@-rootless
+    image: docker.gitea.com/gitea:@dockerVersion@-rootless
    restart: always
 +    user: 1001
    volumes:
@@ -252,13 +252,13 @@ docker-compose up -d
 - 将卷中的文件夹（gitea）重命名为 custom
 - 如果需要，编辑 `app.ini`
  - 设置 `START_SSH_SERVER = true`
- 使用镜像 ` docker.io/gitea/gitea:@dockerVersion@-rootless`
+- 使用镜像 ` docker.gitea.com/gitea:@dockerVersion@-rootless`

 ## 使用环境变量管理部署

 除了上述的环境变量外，`app.ini` 中的任何设置都可以通过形式为 `GITEA__SECTION_NAME__KEY_NAME` 的环境变量进行设置或覆盖。这些设置在每次 Docker 容器启动时都会生效。完整信息请参考[这里](https://github.com/go-gitea/gitea/tree/main/contrib/environment-to-ini).

-这些环境变量可以在 `docker-compose.yml` 中传递给 Docker 容器。以下示例将启用 SMTP 邮件服务器，如果主机上设置了所需的环境变量 GITEA__mailer__FROM、GITEA__mailer__HOST、GITEA__mailer__PASSWD，或者在与 `docker-compose.yml` 相同目录中的 `.env` 文件中设置了这些环境变量：
+这些环境变量可以在 `docker-compose.yml` 中传递给 Docker 容器。以下示例将启用 SMTP 邮件服务器，如果主机上设置了所需的环境变量 GITEA**mailer**FROM、GITEA**mailer**HOST、GITEA**mailer**PASSWD，或者在与 `docker-compose.yml` 相同目录中的 `.env` 文件中设置了这些环境变量：

 ```bash
 ...
@@ -14,7 +14,7 @@ Gitea 在其 Docker Hub 组织内提供自动更新的 Docker 镜像。可以始

 ## 基本

-最简单的设置只是创建一个卷和一个网络，然后将 `gitea/gitea:latest` 镜像作为服务启动。由于没有可用的数据库，因此可以使用 SQLite3 初始化数据库。创建一个类似 `gitea` 的目录，并将以下内容粘贴到名为 `docker-compose.yml` 的文件中。请注意，该卷应由配置文件中指定的 UID/GID 的用户/组拥有。如果您不授予卷正确的权限，则容器可能无法启动。另请注意，标签 `:latest` 将安装当前的开发版本。对于稳定的发行版，您可以使用 `:1` 或指定某个发行版，例如 `@dockerVersion@`。
+最简单的设置只是创建一个卷和一个网络，然后将 `docker.gitea.com/gitea:latest` 镜像作为服务启动。由于没有可用的数据库，因此可以使用 SQLite3 初始化数据库。创建一个类似 `gitea` 的目录，并将以下内容粘贴到名为 `docker-compose.yml` 的文件中。请注意，该卷应由配置文件中指定的 UID/GID 的用户/组拥有。如果您不授予卷正确的权限，则容器可能无法启动。另请注意，标签 `:latest` 将安装当前的开发版本。对于稳定的发行版，您可以使用 `:1` 或指定某个发行版，例如 `@dockerVersion@`。

 ```yaml
 version: "3"
@@ -25,7 +25,7 @@ networks:

 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@
+    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    environment:
      - USER_UID=1000
@@ -55,7 +55,7 @@ networks:

 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@
+    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    environment:
      - USER_UID=1000
@@ -89,7 +89,7 @@ networks:

 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@
+    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    environment:
      - USER_UID=1000
@@ -139,7 +139,7 @@ networks:

 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@
+    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    environment:
      - USER_UID=1000
@@ -192,7 +192,7 @@ networks:
 +
 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@
+    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    restart: always
    networks:
@@ -291,12 +291,12 @@ Gitea 将为每次新安装自动生成新的 `SECRET_KEY` 并将它们写入 `a
 以下命令将向 `stdout` 输出一个新的 `SECRET_KEY` 和 `INTERNAL_TOKEN`，然后您可以将其放入环境变量中。

 ```bash
-docker run -it --rm docker.io/gitea/gitea:1 gitea generate secret SECRET_KEY
-docker run -it --rm docker.io/gitea/gitea:1 gitea generate secret INTERNAL_TOKEN
+docker run -it --rm docker.gitea.com/gitea:1 gitea generate secret SECRET_KEY
+docker run -it --rm docker.gitea.com/gitea:1 gitea generate secret INTERNAL_TOKEN
 ```

 ```yaml
-...
+---
 services:
  server:
    environment:
@@ -343,7 +343,7 @@ ports:
  - "127.0.0.1:2222:22"
 ```

-另外，主机上的 `/home/git/.ssh/authorized_keys` 需要修改。它需要以与 Gitea 容器内的 `authorized_keys` 相同的方式进行操作。因此，将您在上面创建的密钥（“Gitea 主机密钥”）的公共密钥添加到 `~/git/.ssh/authorized_keys`。这可以通过 `echo "$(cat /home/git/.ssh/id_rsa.pub)" >> /home/git/.ssh/authorized_keys` 完成。重要提示：来自 `git` 用户的公钥需要“按原样”添加，而通过 Gitea 网络界面添加的所有其他公钥将以 `command="/app [...]` 作为前缀。
+另外，主机上的 `/home/git/.ssh/authorized_keys` 需要修改。它需要以与 Gitea 容器内的 `authorized_keys` 相同的方式进行操作。因此，将您在上面创建的密钥（“Gitea 主机密钥”）的公共密钥添加到 `/home/git/.ssh/authorized_keys`。这可以通过 `echo "$(cat /home/git/.ssh/id_rsa.pub)" >> /home/git/.ssh/authorized_keys` 完成。重要提示：来自 `git` 用户的公钥需要“按原样”添加，而通过 Gitea 网络界面添加的所有其他公钥将以 `command="/app [...]` 作为前缀。

 该文件应该看起来像：

@@ -5,7 +5,6 @@ slug: "clone-filters"
 sidebar_position: 25
 aliases:
  - /zh-cn/clone-filters
-
 ---

 # 克隆过滤器 (部分克隆)
@@ -5,7 +5,6 @@ slug: "incoming-email"
 sidebar_position: 13
 aliases:
  - /zh-cn/incoming-email
-
 ---

 # 邮件接收