add artifact preview

update to 1.27.3 (#532 )
Preview: https://pr-532.docs-gitea-com.pages.dev Reviewed-on: https://gitea.com/gitea/docs/pulls/532 Reviewed-by: bircni <[email protected]> Co-authored-by: Lunny Xiao <[email protected]>
2026-11-12 12:54:12 +00:00 · 2026-08-30 14:23:03 +02:00 · 2026-08-29 19:59:27 +00:00 · 2026-08-27 05:11:05 +00:00 · 2026-08-25 17:33:20 +00:00 · 2026-08-24 17:16:30 +00:00
2334 changed files with 555846 additions and 6050 deletions
@@ -0,0 +1,13 @@
 root = true
 [*]
 indent_style = space
 indent_size = 2
 tab_width = 2
 end_of_line = lf
 charset = utf-8
 trim_trailing_whitespace = true
 insert_final_newline = true
 [Makefile]
 indent_style = tab
@@ -0,0 +1 @@
 * text=auto eol=lf
@@ -0,0 +1,48 @@
 name: Build and Publish Docs site
 run-name: astro build docs site
 on:
  push:
    branches:
      - main
 jobs:
  build-docs:
    runs-on: ubuntu-24.04
    env:
      NODE_OPTIONS: --max-old-space-size=8192
      # search only appears once the credentials are set, the build falls back
      # to pagefind otherwise
      PUBLIC_DOCSEARCH_APP_ID: ${{ secrets.DOCSEARCH_APP_ID }}
      PUBLIC_DOCSEARCH_API_KEY: ${{ secrets.DOCSEARCH_API_KEY }}
      PUBLIC_DOCSEARCH_INDEX_NAME: ${{ secrets.DOCSEARCH_INDEX_NAME }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
        with:
          node-version: 24
          cache: pnpm
      - name: prepare awesome list
        run: |
          make prepare-awesome-latest prepare-awesome\#27 prepare-awesome\#26 prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22
      - name: Install dependencies
        run: pnpm install --frozen-lockfile
      - name: build site
        run: make build
      - name: Copy files to Cloudflare Pages
        env:
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
        run: |
          # cloudflare/_headers and cloudflare/_redirects are only meaningful for
          # the Cloudflare Pages deployment, so they are copied into the build
          # right before the deploy.
          cp cloudflare/_headers sites/docs/dist/_headers
          cp cloudflare/_redirects sites/docs/dist/_redirects
          test -f sites/docs/dist/_headers -a -f sites/docs/dist/_redirects || exit 1
          pnpm dlx wrangler@4 pages deploy sites/docs/dist \
            --project-name docs-gitea-com \
            --branch main
@@ -0,0 +1,68 @@
 name: cleanup preview
 on:
  pull_request:
    types:
      - closed
 # make sure two closing events for the same pull request do not delete the same
 # deployment twice
 concurrency:
  group: cleanup-preview-${{ github.event.pull_request.number }}
 jobs:
  cleanup-preview:
    runs-on: ubuntu-latest
    steps:
      - name: delete the Cloudflare Pages preview deployments
        env:
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: |
          set -euo pipefail
          # pull requests from forks do not get the secrets, nothing was
          # deployed for them either
          if [ -z "${CLOUDFLARE_API_TOKEN:-}" ] || [ -z "${CLOUDFLARE_ACCOUNT_ID:-}" ]; then
            echo "no Cloudflare credentials available, skipping the preview cleanup"
            exit 0
          fi
          project=docs-gitea-com
          branch="pr-$PR_NUMBER"
          api="https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/pages/projects/$project/deployments"
          page=1
          ids=""
          while true; do
            curl --silent --show-error --fail --output deployments.json \
              -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
              "$api?per_page=100&page=$page"
            found="$(jq -r --arg branch "$branch" \
              '.result[] | select(.deployment_trigger.metadata.branch == $branch) | .id' deployments.json)"
            if [ -n "$found" ]; then
              ids="$ids$found"$'\n'
            fi
            # the API returns an empty result once the last page is passed
            [ "$(jq -r '.result | length' deployments.json)" -eq 100 ] || break
            page=$((page + 1))
          done
          if [ -z "$(printf '%s' "$ids" | tr -d '[:space:]')" ]; then
            echo "no preview deployment found for $branch"
            exit 0
          fi
          # force=true also removes the deployment the branch alias points at
          printf '%s' "$ids" | while read -r id; do
            [ -n "$id" ] || continue
            echo "deleting the deployment $id of $branch"
            curl --silent --show-error --fail --output /dev/null \
              -X DELETE "$api/$id?force=true" \
              -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
          done
          echo "the preview of $branch is gone"
@@ -0,0 +1,103 @@
 name: checks
 on:
  - pull_request
 # a new push to the same pull request replaces the running preview build
 concurrency:
  group: checks-${{ github.event.pull_request.number }}
  cancel-in-progress: true
 jobs:
  build-docs:
    runs-on: ubuntu-latest
    env:
      NODE_OPTIONS: --max-old-space-size=8192
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
        with:
          node-version: 24
          cache: pnpm
      - name: prepare awesome list
        run: |
          make prepare-awesome-latest prepare-awesome\#27 prepare-awesome\#26 prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22
      - name: install dependencies
        run: pnpm install --frozen-lockfile
      - name: build site
        run: make build
      - name: type check
        run: make check
      - name: deploy the preview to Cloudflare Pages
        id: preview
        env:
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: |
          set -euo pipefail
          # pull requests from forks do not get the secrets, the build above is
          # then the only check and the preview is silently skipped
          if [ -z "${CLOUDFLARE_API_TOKEN:-}" ] || [ -z "${CLOUDFLARE_ACCOUNT_ID:-}" ]; then
            echo "no Cloudflare credentials available, skipping the preview deployment"
            exit 0
          fi
          # same as the production deployment: _headers and _redirects only
          # belong to the Cloudflare Pages output, so they are copied in right
          # before uploading
          cp cloudflare/_headers sites/docs/dist/_headers
          cp cloudflare/_redirects sites/docs/dist/_redirects
          pnpm dlx wrangler@4 pages deploy sites/docs/dist \
            --project-name docs-gitea-com \
            --branch "pr-$PR_NUMBER" | tee wrangler.log
          url="$(grep -Eo 'https://[A-Za-z0-9.-]+\.pages\.dev' wrangler.log | tail -n 1)"
          if [ -z "$url" ]; then
            echo "could not read the preview URL from the wrangler output"
            exit 1
          fi
          echo "url=$url" >> "$GITHUB_OUTPUT"
      - name: update the pull request with the preview URL
        if: steps.preview.outputs.url != ''
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
          PREVIEW_URL: ${{ steps.preview.outputs.url }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: |
          set -euo pipefail
          if [ -z "${DEPLOY_TOKEN:-}" ]; then
            echo "secrets.DEPLOY_TOKEN is missing, the preview is at $PREVIEW_URL"
            exit 0
          fi
          api="${GITHUB_API_URL:-$GITHUB_SERVER_URL/api/v1}/repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER"
          curl --silent --show-error --fail --output pull.json \
            -H "Authorization: token $DEPLOY_TOKEN" "$api"
          marker='<!-- cloudflare-preview -->'
          # drop the line written by an earlier run, so the URL is updated in
          # place instead of piling up at the end of the description
          body="$(jq -r '.body // ""' pull.json | grep -vF "$marker" || true)"
          body="$(printf '%s\n' "$body" | sed -e :a -e '/^\n*$/{$d;N;ba' -e '}')"
          if [ -n "$body" ]; then
            body="$(printf '%s\n\n%s Preview: %s\n' "$body" "$marker" "$PREVIEW_URL")"
          else
            body="$(printf '%s Preview: %s\n' "$marker" "$PREVIEW_URL")"
          fi
          jq -n --arg body "$body" '{body: $body}' > patch.json
          curl --silent --show-error --fail --output /dev/null \
            -X PATCH "$api" \
            -H "Authorization: token $DEPLOY_TOKEN" \
            -H 'Content-Type: application/json' \
            --data @patch.json
          echo "the pull request now points at $PREVIEW_URL"
@@ -0,0 +1,109 @@
 name: update runner reference
 on:
  schedule:
    - cron: '30 3 * * 1' # every Monday at 03:30
  workflow_dispatch:
 env:
  # main is protected, so the update is proposed as a pull request from this branch
  BOT_BRANCH: bot/update-runner-reference
  BASE_BRANCH: main
  # the develop runner docs follow the main branch of gitea/runner, every
  # documented release series follows its newest stable tag. The value is used
  # unquoted, so the glob is expanded by the shell of each step.
  TARGET_DIRS: runner-docs/reference runner-docs_versioned_docs/version-*/reference
 jobs:
  update-runner-reference:
    if: github.repository == 'gitea/docs'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          ref: main
          # pushing uses DEPLOY_TOKEN, keep the ephemeral job token out of .git/config
          persist-credentials: false
      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
        with:
          go-version: 'stable'
          cache: false
      - name: regenerate the runner reference pages
        run: |
          set -euo pipefail
          ./update_runner_docs.sh main runner-docs/reference
          ./update_runner_docs.sh --released
      - name: verify the generated files
        run: |
          set -euo pipefail
          # the pages are built from `--help` and `generate-config`, so a truncated
          # build would silently produce an almost empty page
          for dir in $TARGET_DIRS; do
            echo "checking $dir"
            grep -q 'gitea-runner \[command\]' "$dir/cli.md"
            grep -q 'gitea-runner exec \[flags\]' "$dir/cli.md"
            grep -q '^runner:' "$dir/config-example.md"
          done
      - name: push bot branch
        id: bot_branch
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
        run: |
          set -euo pipefail
          if git diff --quiet -- $TARGET_DIRS; then
            echo "the runner reference is already up to date"
            echo "changed=false" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          if [ -z "$DEPLOY_TOKEN" ]; then
            echo "secrets.DEPLOY_TOKEN is missing, cannot push the update"
            exit 1
          fi
          remote="https://x-access-token:$DEPLOY_TOKEN@${GITHUB_SERVER_URL#*://}/$GITHUB_REPOSITORY.git"
          # skip if an open bot branch already carries exactly these files
          if git fetch --quiet --depth=1 "$remote" "refs/heads/$BOT_BRANCH" 2>/dev/null; then
            if git diff --quiet FETCH_HEAD -- $TARGET_DIRS; then
              echo "$BOT_BRANCH already proposes this runner reference"
              echo "changed=false" >> "$GITHUB_OUTPUT"
              exit 0
            fi
          fi
          git config user.name "Gitea Bot"
          git config user.email "[email protected]"
          git switch --create "$BOT_BRANCH"
          git add $TARGET_DIRS
          git commit -m "Update the runner reference pages"
          # force push: the branch is always rebuilt on top of the current main
          git push --force "$remote" "HEAD:refs/heads/$BOT_BRANCH"
          echo "changed=true" >> "$GITHUB_OUTPUT"
      - name: create pull request
        if: steps.bot_branch.outputs.changed == 'true'
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
        run: |
          set -euo pipefail
          cat > pull.json <<EOF
          {
            "base": "$BASE_BRANCH",
            "head": "$BOT_BRANCH",
            "title": "Update the runner reference pages",
            "body": "Automated update of the generated runner reference pages from gitea/runner (main for the develop docs, the newest stable tag for every documented series), opened by the \"update runner reference\" scheduled workflow."
          }
          EOF
          code="$(curl --silent --show-error --output pull-response.json --write-out '%{http_code}' \
            -X POST "${GITHUB_API_URL:-$GITHUB_SERVER_URL/api/v1}/repos/$GITHUB_REPOSITORY/pulls" \
            -H "Authorization: token $DEPLOY_TOKEN" \
            -H 'Content-Type: application/json' \
            --data @pull.json)"
          case "$code" in
            201) echo "pull request created" ;;
            409) echo "an open pull request for $BOT_BRANCH already exists, it now points at the new commit" ;;
            *) echo "unexpected response $code:"; cat pull-response.json; exit 1 ;;
          esac
@@ -0,0 +1,110 @@
 name: update api spec files
 on:
  schedule:
    - cron:  '0 */12 * * *' # every 12 hours on the hour
  workflow_dispatch:
 env:
  # main is protected, so the update is proposed as a pull request from this branch
  BOT_BRANCH: bot/update-swagger-latest
  BASE_BRANCH: main
  # the documents of the gitea main branch, refreshed by this job
  LATEST_FILES: static/swagger-latest.json static/openapi3-latest.json
 jobs:
  update-swagger:
    if: github.repository == 'gitea/docs'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          ref: main
          # pushing uses DEPLOY_TOKEN, keep the ephemeral job token out of .git/config
          persist-credentials: false
      - name: regenerate the latest api documents
        run: make update-api-docs-latest
      - name: verify the generated file
        run: |
          set -euo pipefail
          for file in $LATEST_FILES; do
            # placeholders must have been replaced, otherwise upstream changed them again
            if grep -q -e 'GITEA-API-APP' -e '{{' "$file"; then
              echo "$file still contains template placeholders"
              exit 1
            fi
            if command -v python3 >/dev/null 2>&1; then
              python3 -c "import json,sys; json.load(open(sys.argv[1]))" "$file"
            fi
          done
      - name: push bot branch
        id: bot_branch
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
        run: |
          set -euo pipefail
          if git diff --quiet -- $LATEST_FILES; then
            echo "the api documents are already up to date"
            echo "changed=false" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          if [ -z "$DEPLOY_TOKEN" ]; then
            echo "secrets.DEPLOY_TOKEN is missing, cannot push the update"
            exit 1
          fi
          remote="https://x-access-token:$DEPLOY_TOKEN@${GITHUB_SERVER_URL#*://}/$GITHUB_REPOSITORY.git"
          # skip if an open bot branch already carries exactly this file
          if git fetch --quiet --depth=1 "$remote" "refs/heads/$BOT_BRANCH" 2>/dev/null; then
            same=true
            for file in $LATEST_FILES; do
              old_blob="$(git rev-parse --quiet --verify "FETCH_HEAD:$file" || true)"
              if [ "$old_blob" != "$(git hash-object "$file")" ]; then
                same=false
                break
              fi
            done
            if [ "$same" = true ]; then
              echo "$BOT_BRANCH already proposes these api documents"
              echo "changed=false" >> "$GITHUB_OUTPUT"
              exit 0
            fi
          fi
          git config user.name "Gitea Bot"
          git config user.email "[email protected]"
          git switch --create "$BOT_BRANCH"
          git add $LATEST_FILES
          git commit -m "Update the latest api documents"
          # force push: the branch is always rebuilt on top of the current main
          git push --force "$remote" "HEAD:refs/heads/$BOT_BRANCH"
          echo "changed=true" >> "$GITHUB_OUTPUT"
      - name: create pull request
        if: steps.bot_branch.outputs.changed == 'true'
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
        run: |
          set -euo pipefail
          cat > pull.json <<EOF
          {
            "base": "$BASE_BRANCH",
            "head": "$BOT_BRANCH",
            "title": "Update the latest api documents",
            "body": "Automated update of static/swagger-latest.json and static/openapi3-latest.json from the gitea main branch, opened by the \"update api spec files\" scheduled workflow."
          }
          EOF
          code="$(curl --silent --show-error --output pull-response.json --write-out '%{http_code}' \
            -X POST "${GITHUB_API_URL:-$GITHUB_SERVER_URL/api/v1}/repos/$GITHUB_REPOSITORY/pulls" \
            -H "Authorization: token $DEPLOY_TOKEN" \
            -H 'Content-Type: application/json' \
            --data @pull.json)"
          case "$code" in
            201) echo "pull request created" ;;
            409) echo "an open pull request for $BOT_BRANCH already exists, it now points at the new commit" ;;
            *) echo "unexpected response $code:"; cat pull-response.json; exit 1 ;;
          esac
@@ -0,0 +1,24 @@
 # Dependencies
 node_modules
 # Build output
 sites/*/dist
 sites/*/.astro
 sites/*/.cache
 build/
 .docusaurus/
 # Misc
 .DS_Store
 .env.local
 .env.development.local
 .env.test.local
 .env.production.local
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 .tmp/
 awesome/
 awesome.md
@@ -0,0 +1,202 @@
                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/
   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
   1. Definitions.
      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.
      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.
      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.
      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.
      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.
      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.
      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).
      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.
      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."
      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.
   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.
   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.
   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:
      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and
      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and
      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and
      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.
      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.
   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.
   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.
   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.
   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.
   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.
   END OF TERMS AND CONDITIONS
   APPENDIX: How to apply the Apache License to your work.
      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.
   Copyright [yyyy] [name of copyright owner]
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at
       http://www.apache.org/licenses/LICENSE-2.0
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
@@ -0,0 +1,90 @@
 GITEA_AWESOME_REMOTE := https://gitea.com/gitea/awesome-gitea.git
 GITEA_AWESOME_BRANCH := main
 .PHONY: all
 all: build
 .PHONY: create_dir
 create_dir:
 	mkdir -p .tmp
 .PHONY: clone_awesome
 clone_awesome: create_dir
 	git clone --branch=$(GITEA_AWESOME_BRANCH) $(GITEA_AWESOME_REMOTE) .tmp/upstream-awesome || true
 .PHONY: prepare-awesome-latest
 prepare-awesome-latest: clone_awesome
 	cp .tmp/upstream-awesome/README.md docs/awesome.md
 .PHONY: prepare-awesome\#%
 prepare-awesome\#%:
 	cp .tmp/upstream-awesome/README.md  versioned_docs/version-1.$*/awesome.md
 .PHONY: install
 install:
 	pnpm install
 .PHONY: prepare-docs
 prepare-docs: install prepare-awesome-latest prepare-awesome\#22 prepare-awesome\#23 prepare-awesome\#24 prepare-awesome\#25 prepare-awesome\#26 prepare-awesome\#27
 .PHONY: build
 build:
 	pnpm run build
 # type checks the astro site and its components
 .PHONY: check
 check:
 	pnpm run check
 .PHONY: serve
 serve: prepare-docs
 	pnpm run dev
 # only the english docs of the version served at the root, plus the runner:
 # starts in a few seconds instead of loading the whole matrix
 .PHONY: serve-fast
 serve-fast:
 	pnpm run dev:en-latest
 # search is built by pagefind at build time, so it is only available on the
 # built site; this serves it locally
 .PHONY: serve-built
 serve-built: build
 	pnpm run preview
 .PHONY: clean
 clean:
 	rm -rf .tmp
 	rm -rf sites/docs/dist
 	rm -rf sites/docs/.cache
 	rm -rf sites/docs/node_modules/.astro
 # static/swagger-*.json and static/openapi3-*.json are committed files, use
 # update-api-docs to refresh them
 .PHONY: update-api-docs
 update-api-docs:
 	./update_api_docs.sh
 # only refresh the documents of the gitea main branch (used by the cron job)
 .PHONY: update-api-docs-latest
 update-api-docs-latest:
 	./update_api_docs.sh --latest-only
 # regenerate the generated runner reference pages of the develop docs from the
 # main branch of gitea/runner (used by the update runner reference cron job)
 .PHONY: update-runner-docs
 update-runner-docs:
 	./update_runner_docs.sh main runner-docs/reference
 # same, for every documented release series: the tags are looked up through the
 # Gitea API, so a runner release needs no change here
 .PHONY: update-runner-docs-released
 update-runner-docs-released:
 	./update_runner_docs.sh --released
 # freezes the current docs or runner tree as a new version, see
 # scripts/cut-version.mjs
 .PHONY: cut-version
 cut-version:
 	@test -n "$(PRODUCT)" -a -n "$(VERSION)" || { echo 'usage: make cut-version PRODUCT=docs VERSION=1.28'; exit 1; }
 	node scripts/cut-version.mjs $(PRODUCT) $(VERSION)
@@ -0,0 +1,126 @@
 # Gitea Docs ![badge](https://gitea.com/gitea/docs/actions/workflows/build-and-publish.yaml/badge.svg)
 The sources of [docs.gitea.com](https://docs.gitea.com), built with
 [Astro](https://astro.build) and [Starlight](https://starlight.astro.build).
 The site covers three products, all served from this repository:
 | Product | Content | Versions | Languages |
 | --- | --- | --- | --- |
 | Docs | `docs/`, `versioned_docs/`, `i18n/` | next, 1.27 … 1.22 | English, 简体中文, 繁體中文 |
 | API | `static/swagger-*.json`, `static/openapi3-*.json` | next, 1.27 … 1.22 | English |
 | Runner | `runner-docs/`, `runner-docs_versioned_docs/` | develop, 3 … 0 | English |
 The enterprise documentation is built and deployed from its own repository and
 reached through `/enterprise/`, which a Cloudflare worker maintained elsewhere
 routes to that deployment.
 ## Development
 ```shell
 make install       # pnpm install
 make serve-fast    # english, the version served at the root, starts in seconds
 make serve         # the whole matrix, every version and language
 make build         # production build into sites/docs/dist
 make check         # type checks the site and its components
 ```
 Search is built by Pagefind while the site is built, so it only answers on the
 built site: use `make serve-built` to try it. With the Algolia credentials
 (`PUBLIC_DOCSEARCH_APP_ID`, `PUBLIC_DOCSEARCH_API_KEY`) set, DocSearch is used
 instead and works in `make serve` too.
 `GITEA_DOCS_PRODUCTS`, `GITEA_DOCS_VERSIONS` and `GITEA_DOCS_LOCALES` (comma
 separated) restrict what is built, which is what `make serve-fast` uses.
 `GITEA_DOCS_STRICT_LINKS=true` turns the warnings about unresolved relative
 markdown links into a build error.
 `sites/docs/README.md` documents how the sources are mapped onto the site.
 ## Writing
 Pages are plain markdown with the same frontmatter and admonitions as before:
 frontmatter `slug`, `sidebar_position` and `sidebar_label` keep working, and so
 do the `:::note` style admonitions and the `@version@` style release variables.
 Relative `*.md` links are rewritten to urls while the site is built.
 The order of the top level sidebar groups comes from `sidebars.js` (and
 `versioned_sidebars/` for released versions), the label and order of every other
 group from the `_category_.json` of its directory.
 ## Cutting a version
 ```shell
 make cut-version PRODUCT=docs VERSION=1.28
 make cut-version PRODUCT=runner VERSION=4
 ```
 This freezes the current tree, its translations and its sidebar. The label of
 the version, its release variables (`@version@`, `@dockerVersion@`, ...) and
 which version is served at the root live in
 `packages/content-loader/src/products.ts` and are edited by hand afterwards.
 That file is the single source of truth for the product, version and language
 matrix.
 ## API docs
 The definitions rendered under `/api/` live in `static/`:
 `swagger-latest.json` (gitea main) and `swagger-<minor>.json` (released
 versions) hold the swagger 2.0 document every gitea version ships,
 `openapi3-latest.json` and `openapi3-<minor>.json` the openapi 3.0 document
 gitea generates since 1.27. The openapi 3.0 document is what gets rendered
 where it exists, and both are offered for download on the overview page of the
 version, since code generators cannot read the rendered pages (and several of
 them reject swagger 2.0).
 ```shell
 make update-api-docs         # refresh latest + every released version
 make update-api-docs-latest  # refresh only the documents of gitea main
 ```
 The documents of gitea main are refreshed automatically: the `update api spec
 files` workflow runs every 12 hours and opens a pull request whenever gitea main
 changed. Released versions are updated by hand when a new gitea version is
 documented.
 ## Runner docs
 | Version | Content | URL |
 | --- | --- | --- |
 | develop | `runner-docs/` | `/runner/develop/` |
 | current series | `runner-docs_versioned_docs/version-3/` | `/runner/` |
 | older series | `runner-docs_versioned_docs/version-2/` | `/runner/2/` |
 A version directory covers a whole release series (`version-3` documents every
 `3.x` release), so a patch release only needs a content update, not a new
 folder. Use floating image tags (`gitea/runner:3`) and links to the runner's
 `main` branch in those pages to keep them valid across patch releases.
 Its sidebar is written by hand: `runner-sidebars.js` for develop, and
 `runner-docs_versioned_sidebars/version-<version>-sidebars.json` per documented
 version.
 The pages under `reference/` are generated from the runner sources — the command
 line reference from `--help`, the example configuration from `generate-config`:
 ```shell
 make update-runner-docs           # develop docs, from the main branch of gitea/runner
 make update-runner-docs-released  # every series, from its newest stable tag
 ./update_runner_docs.sh v3.0.2 runner-docs_versioned_docs/version-3/reference
 ```
 These are refreshed automatically as well: the `update runner reference`
 workflow runs weekly and opens a pull request whenever the runner's CLI or
 example configuration changed. Generating them needs Go, since the script builds
 the runner binary.
 ## Deployment
 `main` is built and published by the `Build and Publish Docs site` workflow, to
 S3/CloudFront and to Cloudflare Pages. `cloudflare/_headers` sets the cache
 policy and `cloudflare/_redirects` keeps the urls the site used to serve; both
 are copied next to the build output by that workflow.
 `cloudflare/docsearch-crawler.json` is the Algolia crawler configuration.
 `/enterprise/` is served by another deployment and routed to it by a Cloudflare
 worker that lives outside this repository.
@@ -1,57 +0,0 @@
 ---
 date: "2017-04-08T11:34:00+02:00"
 title: "环境变量清单"
 slug: "environment-variables"
 sidebar_position: 10
 toc: false
 draft: false
 aliases:
  - /zh-cn/environment-variables
 menu:
  sidebar:
    parent: "administration"
    name: "环境变量清单"
    sidebar_position: 10
    identifier: "environment-variables"
 ---
 # 环境变量清单
 这里是用来控制 Gitea 行为表现的的环境变量清单，您需要在执行如下 Gitea 启动命令前设置它们来确保配置生效：
 ```
 GITEA_CUSTOM=/home/gitea/custom ./gitea web
 ```
 ## Go 的配置
 因为 Gitea 使用 Go 语言编写，因此它使用了一些相关的 Go 的配置参数：
 * `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` 替代
 ## 操作系统配置
 * `USER`：Gitea 运行时使用的系统用户，它将作为一些 repository 的访问地址的一部分
 * `USERNAME`： 如果没有配置 `USER`， Gitea 将使用 `USERNAME`
 * `HOME`： 用户的 home 目录，在 Windows 中会使用 `USERPROFILE` 环境变量
 ### 仅限于 Windows 的配置
 * `USERPROFILE`： 用户的主目录，如果未配置则会使用 `HOMEDRIVE` + `HOMEPATH`
 * `HOMEDRIVE`: 用于访问 home 目录的主驱动器路径（C盘）
 * `HOMEPATH`：在指定主驱动器下的 home 目录相对路径
 ## Miscellaneous
 * `SKIP_MINWINSVC`：如果设置为 1，在 Windows 上不会以 service 的形式运行。
@@ -1,261 +0,0 @@
 ---
 date: "2023-05-23T09:00:00+08:00"
 title: "邮件模板"
 slug: "mail-templates"
 sidebar_position: 45
 toc: false
 draft: false
 aliases:
  - /zh-cn/mail-templates
 menu:
  sidebar:
    parent: "administration"
    name: "邮件模板"
    sidebar_position: 45
    identifier: "mail-templates"
 ---
 # 邮件模板
 为了定制特定操作的电子邮件主题和内容，可以使用模板来自定义 Gitea。这些功能的模板位于 [`custom` 目录](administration/customizing-gitea.md) 下。
 如果没有自定义的替代方案，Gitea 将使用内部模板作为默认模板。
 自定义模板在 Gitea 启动时加载。对它们的更改在 Gitea 重新启动之前不会被识别。
 ## 支持模板的邮件通知
 目前，以下通知事件使用模板：
 | 操作名称   | 用途                                                                                    |
 | ----------- | ------------------------------------------------------------------------------------------------------------ |
 | `new`       | 创建了新的工单或合并请求。                                                                    |
 | `comment`   | 在现有工单或合并请求中创建了新的评论。                                                          |
 | `close`     | 关闭了工单或合并请求。                                                                         |
 | `reopen`    | 重新打开了工单或合并请求。                                                                       |
 | `review`    | 在合并请求中进行审查的首要评论。                                                               |
 | `approve`   | 对合并请求进行批准的首要评论。                                                                 |
 | `reject`    | 对合并请求提出更改请求的审查的首要评论。                                                       |
 | `code`      | 关于合并请求的代码的单个评论。                                                                 |
 | `assigned`  | 用户被分配到工单或合并请求。                                                                    |
 | `default`   | 未包括在上述类别中的任何操作，或者当对应类别的模板不存在时使用的模板。                              |
 特定消息类型的模板路径为：
 ```sh
 custom/templates/mail/{操作类型}/{操作名称}.tmpl
 ```
 其中 `{操作类型}` 是 `issue` 或 `pull`（针对合并请求），`{操作名称}` 是上述列出的操作名称之一。
 例如，有关合并请求中的评论的电子邮件的特定模板是：
 ```sh
 custom/templates/mail/pull/comment.tmpl
 ```
 然而，并不需要为每个操作类型/名称组合创建模板。
 使用回退系统来选择适当的模板。在此列表中，将使用 _第一个存在的_ 模板：
 - 所需**操作类型**和**操作名称**的特定模板。
 - 操作类型为 `issue` 和所需**操作名称**的模板。
 - 所需**操作类型**和操作名称为 `default` 的模板。
 - 操作类型为` issue` 和操作名称为 `default` 的模板。
 唯一必需的模板是操作类型为 `issue` 操作名称为 `default` 的模板，除非用户在 `custom` 目录中覆盖了它。
 ## 模板语法
 邮件模板是 UTF-8 编码的文本文件，需要遵循以下格式之一：
 ```
 用于主题行的文本和宏
 ------------
 用于邮件正文的文本和宏
 ```
 或者
 ```
 用于邮件正文的文本和宏
 ```
 指定 _主题_ 部分是可选的（因此也是虚线分隔符）。在使用时，_主题_ 和 _邮件正文_ 模板之间的分隔符需要至少三个虚线；分隔符行中不允许使用其他字符。
 _主题_ 和 _邮件正文_ 由 [Golang的模板引擎](https://go.dev/pkg/text/template/) 解析，并提供了为每个通知组装的 _元数据上下文_。上下文包含以下元素：
 | 名称                 | 类型               | 可用性            | 用途                                                                                                                                                                                                                                             |
 | -------------------- | ------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `.FallbackSubject`   | string             | 始终可用        | 默认主题行。参见下文。                                                                                                                                                                                                                            |
 | `.Subject`           | string             | 仅在正文中可用  | 解析后的 _主题_。                                                                                                                                                                                                                                 |
 | `.Body`              | string             | 始终可用        | 工单、合并请求或评论的消息，从 Markdown 解析为 HTML 并进行了清理。请勿与 _邮件正文_ 混淆。                                                                                                                                                                 |
 | `.Link`              | string             | 始终可用        | 源工单、合并请求或评论的地址。                                                                                                                                                                                                                    |
 | `.Issue`             | models.Issue       | 始终可用        | 产生通知的工单（或合并请求）。要获取特定于合并请求的数据（例如 `HasMerged`），可以使用 `.Issue.PullRequest`，但需要注意，如果工单 _不是_ 合并请求，则该字段将为 `nil`。                                                                       |
 | `.Comment`           | models.Comment     | 如果适用        | 如果通知是针对添加到工单或合并请求的评论，则其中包含有关评论的信息。                                                                                                                                                                             |
 | `.IsPull`            | bool               | 始终可用        | 如果邮件通知与合并请求关联（即 `.Issue.PullRequest` 不为 `nil` ），则为 `true`。                                                                                                                                                                       |
 | `.Repo`              | string         | 始终可用        | 仓库的名称，包括所有者名称（例如 `mike/stuff`）                                                                                                                                                                                                    |
 | `.User`              | models.User        | 始终可用        | 事件来源仓库的所有者。要获取用户名（例如 `mike`），可以使用 `.User.Name`。                                                                                                                                                                           |
 | `.Doer`              | models.User        | 始终可用        | 执行触发通知事件的操作的用户。要获取用户名（例如 `rhonda`），可以使用 `.Doer.Name`。                                                                                                                                                                |
 | `.IsMention`         | bool               | 始终可用        | 如果此通知仅是因为在评论中提到了用户而生成的，并且收件人未订阅源，则为 `true`。如果收件人已订阅工单或仓库，则为 `false`。                                                                                                                            |
 | `.SubjectPrefix`     | string             | 始终可用        | 如果通知是关于除工单或合并请求创建之外的其他内容，则为 `Re：`；否则为空字符串。                                                                                                                                                                      |
 | `.ActionType`        | string             | 始终可用        | `"issue"` 或 `"pull"`。它将与实际的 _操作类型_ 对应，与选择的模板无关。                                                                                                                                                                                 |
 | `.ActionName`        | string             | 始终可用        | 它将是上述操作类型之一（`new` ，`comment` 等），并与选择的模板对应。                                                                                                                                                                                 |
 | `.ReviewComments`    | []models.Comment   | 始终可用        | 审查中的代码评论列表。评论文本将在 `.RenderedContent` 中，引用的代码将在 `.Patch` 中。                                                                                                                                                                |
 所有名称区分大小写。
 ### 模板中的主题部分
 用于邮件主题的模板引擎是 Golang 的 [`text/template`](https://go.dev/pkg/text/template/)。
 有关语法的详细信息，请参阅链接的文档。
 主题构建的步骤如下：
 - 根据通知类型和可用的模板选择一个模板。
 - 解析并解析模板（例如，将 `{{.Issue.Index}}` 转换为工单或合并请求的编号）。
 - 将所有空格字符（例如 `TAB`，`LF` 等）转换为普通空格。
 - 删除所有前导、尾随和多余的空格。
 - 将字符串截断为前 256 个字母（字符）。
 如果最终结果为空字符串，**或者**没有可用的主题模板（即所选模板不包含主题部分），将使用Gitea的**内部默认值**。
 内部默认（回退）主题相当于：
 ```
 {{.SubjectPrefix}}[{{.Repo}}] {{.Issue.Title}} (#{{.Issue.Index}})
 ```
 例如：`Re: [mike/stuff] New color palette (#38)`
 即使存在有效的主题模板，Gitea的默认主题也可以在模板的元数据中作为 `.FallbackSubject` 找到。
 ### 模板中的邮件正文部分
 用于邮件正文的模板引擎是 Golang 的 [`html/template`](https://go.dev/pkg/html/template/)。
 有关语法的详细信息，请参阅链接的文档。
 邮件正文在邮件主题之后进行解析，因此还有一个额外的 _元数据_ 字段，即在考虑所有情况之后实际呈现的主题。
 期望的结果是 HTML（包括结构元素，如`<html>`，`<body>`等）。可以通过 `<style>` 块、`class` 和 `style` 属性进行样式设置。但是，`html/template` 会进行一些 [自动转义](https://go.dev/pkg/html/template/#hdr-Contexts)，需要考虑这一点。
 不支持附件（例如图像或外部样式表）。但是，也可以引用其他模板，例如以集中方式提供 `<style>` 元素的内容。外部模板必须放置在 `custom/mail` 下，并相对于该目录引用。例如，可以使用 `{{template styles/base}}` 包含 `custom/mail/styles/base.tmpl`。
 邮件以 `Content-Type: multipart/alternative` 发送，因此正文以 HTML 和文本格式发送。通过剥离 HTML 标记来获取文本版本。
 ## 故障排除
 邮件的呈现方式直接取决于邮件应用程序的功能。许多邮件客户端甚至不支持 HTML，因此显示生成邮件中包含的文本版本。
 如果模板无法呈现，则只有在发送邮件时才会注意到。
 如果主题模板失败，将使用默认主题，如果从 _邮件正文_ 中成功呈现了任何内容，则将使用该内容，忽略其他内容。
 如果遇到问题，请检查 [Gitea的日志](administration/logging-config.md) 以获取错误消息。
 ## 示例
 `custom/templates/mail/issue/default.tmpl`:
 ```html
 [{{.Repo}}] @{{.Doer.Name}}
 {{if eq .ActionName "new"}}
    创建了
 {{else if eq .ActionName "comment"}}
    评论了
 {{else if eq .ActionName "close"}}
    关闭了
 {{else if eq .ActionName "reopen"}}
    重新打开了
 {{else}}
    更新了
 {{end}}
 {{if eq .ActionType "issue"}}
    工单
 {{else}}
    合并请求
 {{end}}
 #{{.Issue.Index}}: {{.Issue.Title}}
 ------------
 <!DOCTYPE html>
 <html>
 <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>{{.Subject}}</title>
 </head>
 <body>
    {{if .IsMention}}
    <p>
        您收到此邮件是因为 @{{.Doer.Name}} 提到了您。
    </p>
    {{end}}
    <p>
        <p>
        <a href="{{AppUrl}}/{{.Doer.LowerName}}">@{{.Doer.Name}}</a>
        {{if not (eq .Doer.FullName "")}}
            ({{.Doer.FullName}})
        {{end}}
        {{if eq .ActionName "new"}}
            创建了
        {{else if eq .ActionName "close"}}
            关闭了
        {{else if eq .ActionName "reopen"}}
            重新打开了
        {{else}}
            更新了
        {{end}}
        <a href="{{.Link}}">{{.Repo}}#{{.Issue.Index}}</a>。
        </p>
        {{if not (eq .Body "")}}
            <h3>消息内容：</h3>
            <hr>
            {{.Body}}
        {{end}}
    </p>
    <hr>
    <p>
        <a href="{{.Link}}">在 Gitea 上查看</a>。
    </p>
 </body>
 </html>
 ```
 该模板将生成以下内容：
 ### 主题
 > [mike/stuff] @rhonda 在合并请求 #38 上进行了评论：New color palette
 ### 邮件正文
 > [@rhonda](#)（Rhonda Myers）更新了 [mike/stuff#38](#)。
 >
 > #### 消息内容
 >
 > \_********************************\_********************************
 >
 > Mike, I think we should tone down the blues a little.
 >
 > \_********************************\_********************************
 >
 > [在 Gitea 上查看](#)。
 ## 高级用法
 模板系统包含一些函数，可用于进一步处理和格式化消息。以下是其中一些函数的列表：
 | 函数名              | 参数        | 可用于       | 用法                             |
 |------------------| ----------- | ------------ | ------------------------------ |
 | `AppUrl`         | -           | 任何地方     | Gitea 的 URL                    |
 | `AppName`        | -           | 任何地方     | 从 `app.ini` 中设置，通常为 "Gitea"    |
 | `AppDomain`      | -           | 任何地方     | Gitea 的主机名                     |
 | `EllipsisString` | string, int | 任何地方     | 将字符串截断为指定长度；根据需要添加省略号          |
 | `SanitizeHTML`   | string      | 仅正文部分   | 通过删除其中的危险 HTML 标签对文本进行清理       |
 | `SafeHTML`       | string      | 仅正文部分   | 将输入作为 HTML 处理；可用于输出原始的 HTML 内容 |
 这些都是 _函数_，而不是元数据，因此必须按以下方式使用：
 ```html
 像这样使用：         {{SanitizeHTML "Escape<my>text"}}
 或者这样使用：       {{"Escape<my>text" | SanitizeHTML}}
 或者这样使用：       {{AppUrl}}
 但不要像这样使用：   {{.AppUrl}}
 ```
@@ -1,136 +0,0 @@
 ---
 date: "2018-05-22T11:00:00+00:00"
 title: "反向代理"
 slug: "reverse-proxies"
 sidebar_position: 16
 toc: false
 draft: false
 aliases:
  - /zh-cn/reverse-proxies
 menu:
  sidebar:
    parent: "administration"
    name: "反向代理"
    sidebar_position: 16
    identifier: "reverse-proxies"
 ---
 # 反向代理
 ## 使用 Nginx 作为反向代理服务
 如果您想使用 Nginx 作为 Gitea 的反向代理服务，您可以参照以下 `nginx.conf` 配置中 `server` 的 `http` 部分：
 ```
 server {
    listen 80;
    server_name git.example.com;
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
 }
 ```
 ## 使用 Nginx 作为反向代理服务并将 Gitea 路由至一个子路径
 如果您已经有一个域名并且想与 Gitea 共享该域名，您可以增加以下 `nginx.conf` 配置中 `server` 的 `http` 部分，为 Gitea 添加路由规则：
 ```
 server {
    listen 80;
    server_name git.example.com;
    # 注意: /git/ 最后需要有一个路径符号
    location /git/ {
        # 注意: 反向代理后端 URL 的最后需要有一个路径符号
        proxy_pass http://localhost:3000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
 }
 ```
 然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://git.example.com/git/` 的配置项。
 ## 使用 Apache HTTPD 作为反向代理服务
 如果您想使用 Apache HTTPD 作为 Gitea 的反向代理服务，您可以为您的 Apache HTTPD 作如下配置（在 Ubuntu 中，配置文件通常在 `/etc/apache2/httpd.conf` 目录下）：
 ```
 <VirtualHost *:80>
    ...
    ProxyPreserveHost On
    ProxyRequests off
    AllowEncodedSlashes NoDecode
    ProxyPass / http://localhost:3000/ nocanon
 </VirtualHost>
 ```
 注：必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`
 ## 使用 Apache HTTPD 作为反向代理服务并将 Gitea 路由至一个子路径
 如果您已经有一个域名并且想与 Gitea 共享该域名，您可以增加以下配置为 Gitea 添加路由规则（在 Ubuntu 中，配置文件通常在 `/etc/apache2/httpd.conf` 目录下）：
 ```
 <VirtualHost *:80>
    ...
    <Proxy *>
         Order allow,deny
         Allow from all
    </Proxy>
    AllowEncodedSlashes NoDecode
    # 注意: 路径和 URL 后面都不要写路径符号 '/'
    ProxyPass /git http://localhost:3000 nocanon
 </VirtualHost>
 ```
 然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://git.example.com/git/` 的配置项。
 注：必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`
 ## 使用 Caddy 作为反向代理服务
 如果您想使用 Caddy 作为 Gitea 的反向代理服务，您可以在 `Caddyfile` 中添加如下配置：
 ```
 git.example.com {
    proxy / http://localhost:3000
 }
 ```
 ## 使用 Caddy 作为反向代理服务并将 Gitea 路由至一个子路径
 如果您已经有一个域名并且想与 Gitea 共享该域名，您可以在您的 `Caddyfile` 文件中增加以下配置，为 Gitea 添加路由规则：
 ```
 git.example.com {
    # 注意: 路径 /git/ 最后需要有路径符号
    proxy /git/ http://localhost:3000
 }
 ```
 然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://git.example.com/git/` 的配置项。
 ## 使用 Traefik 作为反向代理服务
 如果您想使用 traefik 作为 Gitea 的反向代理服务，您可以在 `docker-compose.yaml` 中添加 label 部分（假设使用 docker 作为 traefik 的 provider）：
 ```yaml
 gitea:
  image: gitea/gitea
  ...
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.gitea.rule=Host(`example.com`)"
    - "traefik.http.services.gitea-websecure.loadbalancer.server.port=3000"
 ```
 这份配置假设您使用 traefik 来处理 HTTPS 服务，并在其和 Gitea 之间使用 HTTP 进行通信。
@@ -0,0 +1,37 @@
 #!/bin/bash
 # This script takes `locale` as a param and checks if a specific locale version of document is up to date with English version
 # If latest commit timestamp of English version is greater than the specific locale version,
 # The specific locale version document will be marked as outdated
 set -xe
 SED_INPLACE() {
  if sed --version 2>/dev/null | grep -q GNU; then
    sed -i "$@"
  else
    sed -i '' "$@"
  fi
 }
 locale="$1"
 cur_path=`pwd`
 cd .tmp/upstream-docs
 for file in `find ./docs/content -name "*.${locale}.md"`; do
    file_en="${file/.${locale}/.en-us}"
    if [ ! -f "$file_en" ]; then
        continue
    fi
    latest_commit_time_en=$(git log -1 --format=%ct "$file_en")
    latest_commit_time_locale=$(git log -1 --format=%ct "$file")
    if [ -z "$latest_commit_time_locale" ]; then
        continue
    fi
    if [[ "$latest_commit_time_en" -gt "$latest_commit_time_locale" ]]; then
        echo "file: $file, lastest commit timestamp: $latest_commit_time_en (en ver), $latest_commit_time_locale ($locale ver)"
        SED_INPLACE '1s/---/---\nisOutdated: true/' $file
    fi
 done
 cd "$cur_path"
@@ -0,0 +1,24 @@
 # Cloudflare Pages reads this file from the root of the deployed directory. It
 # is copied into the build output by the publish workflow, so that it is not
 # uploaded to S3/CloudFront where it would be publicly readable at /_headers.
 #
 # Unlike the docusaurus build, astro emits a single content hashed asset
 # directory shared by every language, so no per locale rules are needed.
 # Content hashed build output (js, css, fonts). The file name changes with the
 # content, so these can be cached forever.
 /_astro/*
  Cache-Control: public, max-age=31536000, immutable
 # Files under public/img and public/images keep stable names and are replaced in
 # place, so they get a short, conservative max-age instead.
 /img/*
  Cache-Control: public, max-age=86400
 /images/*
  Cache-Control: public, max-age=86400
 # The pagefind index, only present when the site is built without algolia
 # docsearch. Content hashed as well.
 /pagefind/*
  Cache-Control: public, max-age=31536000, immutable
@@ -0,0 +1,458 @@
 # Redirects for legacy URLs and routes the site no longer serves directly.
 # The api reference and the runner docs are separate products, published in
 # english only. Docusaurus served an empty localized copy of them.
 /zh-cn/api/* /api/:splat 301
 /zh-tw/api/* /api/:splat 301
 /zh-cn/runner/* /runner/:splat 301
 /zh-tw/runner/* /runner/:splat 301
 # The version served at the root of a product is also reachable under its
 # number, which is what the release notes and old links use.
 /api/1.27/* /api/:splat 301
 /runner/3/* /runner/:splat 301
 /1.27/* /:splat 301
 # The local search plugin had a results page of its own, algolia docsearch is a
 # modal opened from any page.
 /search /  301
 /zh-cn/search /zh-cn/ 301
 /zh-tw/search /zh-tw/ 301
 # Pages that moved when the docs were reorganized: the flat `/usage/webhooks`,
 # `/advanced/...` and `/developers/...` layout of 1.19 and 1.20, and
 # `/help/seek-help`. Those urls kept working until the site moved to Cloudflare
 # because it was published with `aws s3 sync` without `--delete`, so the pages
 # built before the move were never removed from the bucket. Only what the build
 # emits is served now, and gitea itself and blog.gitea.com still link to some of
 # them, so they are redirected here.
 /actions                                          /usage/actions/ 301
 /actions/                                         /usage/actions/ 301
 /administration                                   /category/administration/ 301
 /administration/                                  /category/administration/ 301
 /administration/logging-configuration             /administration/logging-config/ 301
 /advanced/adding-legal-pages                      /administration/adding-legal-pages/ 301
 /advanced/clone-filters                           /usage/repository/clone-filters/ 301
 /advanced/cmd-embedded                            /administration/cmd-embedded/ 301
 /advanced/config-cheat-sheet                      /administration/config-cheat-sheet/ 301
 /advanced/customizing-gitea                       /administration/customizing-gitea/ 301
 /advanced/environment-variables                   /administration/environment-variables/ 301
 /advanced/external-renderers                      /administration/external-renderers/ 301
 /advanced/logging-configuration                   /administration/logging-config/ 301
 /advanced/mail-templates                          /administration/mail-templates/ 301
 /advanced/protected-tags                          /usage/access-control/protected-tags/ 301
 /advanced/repo-indexer                            /administration/repo-indexer/ 301
 /advanced/repo-mirror                             /usage/repository/repo-mirror/ 301
 /advanced/search-engines-indexation               /administration/search-engines-indexation/ 301
 /advanced/signing                                 /administration/signing/ 301
 /developers/api-usage                             /development/api-usage/ 301
 /developers/integrations                          /development/integrations/ 301
 /developers/migrations-interfaces                 /development/migrations-interfaces/ 301
 /developers/oauth2-provider                       /development/oauth2-provider/ 301
 /development                                      /category/development/ 301
 /development/                                     /category/development/ 301
 /features/authentication                          /administration/authentication/ 301
 /features/comparison                              /installation/comparison/ 301
 /features/webhooks                                /usage/repository/webhooks/ 301
 /help                                             /category/help/ 301
 /help/                                            /category/help/ 301
 /help/seek-help                                   /help/support/ 301
 /installation                                     /category/installation/ 301
 /installation/                                    /category/installation/ 301
 /installation/upgrade-from-gogs                   /category/installation/ 301
 /upgrade/upgrade-from-gitea                       /installation/upgrade-from-gitea/ 301
 /upgrade/upgrade-from-gogs                        /category/installation/ 301
 /usage                                            /category/usage/ 301
 /usage/                                           /category/usage/ 301
 /usage/actions/act-runner                         /runner/ 301
 /usage/agit                                       /usage/issues-prs/agit/ 301
 /usage/agit-setup                                 /usage/issues-prs/agit/ 301
 /usage/authentication                             /administration/authentication/ 301
 /usage/automatically-linked-references            /usage/issues-prs/automatically-linked-references/ 301
 /usage/badge                                      /usage/actions/badge/ 301
 /usage/blame                                      /usage/repository/blame/ 301
 /usage/blocking-user                              /usage/access-control/blocking-user/ 301
 /usage/clone-filters                              /usage/repository/clone-filters/ 301
 /usage/code-owners                                /usage/repository/code-owners/ 301
 /usage/command-line                               /administration/command-line/ 301
 /usage/email-setup                                /administration/email-setup/ 301
 /usage/git-lfs-setup                              /administration/git-lfs-setup/ 301
 /usage/https-setup                                /administration/https-setup/ 301
 /usage/incoming-email                             /usage/repository/incoming-email/ 301
 /usage/issue-pull-request-templates               /usage/issues-prs/issue-pull-request-templates/ 301
 /usage/labels                                     /usage/issues-prs/labels/ 301
 /usage/markdown                                   /usage/repository/markdown/ 301
 /usage/merge-message-templates                    /usage/issues-prs/merge-message-templates/ 301
 /usage/migration                                  /usage/repository/migration/ 301
 /usage/multi-factor-authentication                /usage/user-setting/multi-factor-authentication/ 301
 /usage/permissions                                /usage/access-control/permissions/ 301
 /usage/profile-readme                             /usage/repository/profile-readme/ 301
 /usage/protected-tags                             /usage/access-control/protected-tags/ 301
 /usage/pull-request                               /usage/issues-prs/pull-request/ 301
 /usage/push                                       /usage/repository/push/ 301
 /usage/push-options                               /usage/repository/push/ 301
 /usage/push-to-create                             /usage/repository/push/ 301
 /usage/repo-mirror                                /usage/repository/repo-mirror/ 301
 /usage/secrets                                    /usage/actions/secrets/ 301
 /usage/template-repositories                      /usage/repository/template-repositories/ 301
 /usage/webhooks                                   /usage/repository/webhooks/ 301
 # ... and under simplified chinese.
 /zh-cn/actions                                    /zh-cn/usage/actions/ 301
 /zh-cn/actions/                                   /zh-cn/usage/actions/ 301
 /zh-cn/administration                             /zh-cn/category/administration/ 301
 /zh-cn/administration/                            /zh-cn/category/administration/ 301
 /zh-cn/administration/logging-configuration       /zh-cn/administration/logging-config/ 301
 /zh-cn/advanced/adding-legal-pages                /zh-cn/administration/adding-legal-pages/ 301
 /zh-cn/advanced/clone-filters                     /zh-cn/usage/repository/clone-filters/ 301
 /zh-cn/advanced/cmd-embedded                      /zh-cn/administration/cmd-embedded/ 301
 /zh-cn/advanced/config-cheat-sheet                /zh-cn/administration/config-cheat-sheet/ 301
 /zh-cn/advanced/customizing-gitea                 /zh-cn/administration/customizing-gitea/ 301
 /zh-cn/advanced/environment-variables             /zh-cn/administration/environment-variables/ 301
 /zh-cn/advanced/external-renderers                /zh-cn/administration/external-renderers/ 301
 /zh-cn/advanced/logging-configuration             /zh-cn/administration/logging-config/ 301
 /zh-cn/advanced/mail-templates                    /zh-cn/administration/mail-templates/ 301
 /zh-cn/advanced/protected-tags                    /zh-cn/usage/access-control/protected-tags/ 301
 /zh-cn/advanced/repo-indexer                      /zh-cn/administration/repo-indexer/ 301
 /zh-cn/advanced/repo-mirror                       /zh-cn/usage/repository/repo-mirror/ 301
 /zh-cn/advanced/search-engines-indexation         /zh-cn/administration/search-engines-indexation/ 301
 /zh-cn/advanced/signing                           /zh-cn/administration/signing/ 301
 /zh-cn/developers/api-usage                       /zh-cn/development/api-usage/ 301
 /zh-cn/developers/integrations                    /zh-cn/development/integrations/ 301
 /zh-cn/developers/migrations-interfaces           /zh-cn/development/migrations-interfaces/ 301
 /zh-cn/developers/oauth2-provider                 /zh-cn/development/oauth2-provider/ 301
 /zh-cn/development                                /zh-cn/category/development/ 301
 /zh-cn/development/                               /zh-cn/category/development/ 301
 /zh-cn/features/authentication                    /zh-cn/administration/authentication/ 301
 /zh-cn/features/comparison                        /zh-cn/installation/comparison/ 301
 /zh-cn/features/webhooks                          /zh-cn/usage/repository/webhooks/ 301
 /zh-cn/help                                       /zh-cn/category/help/ 301
 /zh-cn/help/                                      /zh-cn/category/help/ 301
 /zh-cn/help/seek-help                             /zh-cn/help/support/ 301
 /zh-cn/installation                               /zh-cn/category/installation/ 301
 /zh-cn/installation/                              /zh-cn/category/installation/ 301
 /zh-cn/installation/upgrade-from-gogs             /zh-cn/category/installation/ 301
 /zh-cn/upgrade/upgrade-from-gitea                 /zh-cn/installation/upgrade-from-gitea/ 301
 /zh-cn/upgrade/upgrade-from-gogs                  /zh-cn/category/installation/ 301
 /zh-cn/usage                                      /zh-cn/category/usage/ 301
 /zh-cn/usage/                                     /zh-cn/category/usage/ 301
 /zh-cn/usage/actions/act-runner                   /runner/ 301
 /zh-cn/usage/agit-setup                           /zh-cn/usage/issues-prs/agit/ 301
 /zh-cn/usage/authentication                       /zh-cn/administration/authentication/ 301
 /zh-cn/usage/automatically-linked-references      /zh-cn/usage/issues-prs/automatically-linked-references/ 301
 /zh-cn/usage/badge                                /zh-cn/usage/actions/badge/ 301
 /zh-cn/usage/blame                                /zh-cn/usage/repository/blame/ 301
 /zh-cn/usage/blocking-user                        /zh-cn/usage/access-control/blocking-user/ 301
 /zh-cn/usage/clone-filters                        /zh-cn/usage/repository/clone-filters/ 301
 /zh-cn/usage/code-owners                          /zh-cn/usage/repository/code-owners/ 301
 /zh-cn/usage/command-line                         /zh-cn/administration/command-line/ 301
 /zh-cn/usage/email-setup                          /zh-cn/administration/email-setup/ 301
 /zh-cn/usage/git-lfs-setup                        /zh-cn/administration/git-lfs-setup/ 301
 /zh-cn/usage/https-setup                          /zh-cn/administration/https-setup/ 301
 /zh-cn/usage/incoming-email                       /zh-cn/usage/repository/incoming-email/ 301
 /zh-cn/usage/issue-pull-request-templates         /zh-cn/usage/issues-prs/issue-pull-request-templates/ 301
 /zh-cn/usage/labels                               /zh-cn/usage/issues-prs/labels/ 301
 /zh-cn/usage/markdown                             /zh-cn/usage/repository/markdown/ 301
 /zh-cn/usage/merge-message-templates              /zh-cn/usage/issues-prs/merge-message-templates/ 301
 /zh-cn/usage/migration                            /zh-cn/usage/repository/migration/ 301
 /zh-cn/usage/multi-factor-authentication          /zh-cn/usage/user-setting/multi-factor-authentication/ 301
 /zh-cn/usage/permissions                          /zh-cn/usage/access-control/permissions/ 301
 /zh-cn/usage/profile-readme                       /zh-cn/usage/repository/profile-readme/ 301
 /zh-cn/usage/protected-tags                       /zh-cn/usage/access-control/protected-tags/ 301
 /zh-cn/usage/pull-request                         /zh-cn/usage/issues-prs/pull-request/ 301
 /zh-cn/usage/push                                 /zh-cn/usage/repository/push/ 301
 /zh-cn/usage/push-options                         /zh-cn/usage/repository/push/ 301
 /zh-cn/usage/push-to-create                       /zh-cn/usage/repository/push/ 301
 /zh-cn/usage/repo-mirror                          /zh-cn/usage/repository/repo-mirror/ 301
 /zh-cn/usage/secrets                              /zh-cn/usage/actions/secrets/ 301
 /zh-cn/usage/template-repositories                /zh-cn/usage/repository/template-repositories/ 301
 /zh-cn/usage/webhooks                             /zh-cn/usage/repository/webhooks/ 301
 # ... and under traditional chinese.
 /zh-tw/actions                                    /zh-tw/usage/actions/ 301
 /zh-tw/actions/                                   /zh-tw/usage/actions/ 301
 /zh-tw/administration                             /zh-tw/category/administration/ 301
 /zh-tw/administration/                            /zh-tw/category/administration/ 301
 /zh-tw/administration/logging-configuration       /zh-tw/administration/logging-config/ 301
 /zh-tw/advanced/adding-legal-pages                /zh-tw/administration/adding-legal-pages/ 301
 /zh-tw/advanced/clone-filters                     /zh-tw/usage/repository/clone-filters/ 301
 /zh-tw/advanced/cmd-embedded                      /zh-tw/administration/cmd-embedded/ 301
 /zh-tw/advanced/config-cheat-sheet                /zh-tw/administration/config-cheat-sheet/ 301
 /zh-tw/advanced/customizing-gitea                 /zh-tw/administration/customizing-gitea/ 301
 /zh-tw/advanced/environment-variables             /zh-tw/administration/environment-variables/ 301
 /zh-tw/advanced/external-renderers                /zh-tw/administration/external-renderers/ 301
 /zh-tw/advanced/logging-configuration             /zh-tw/administration/logging-config/ 301
 /zh-tw/advanced/mail-templates                    /zh-tw/administration/mail-templates/ 301
 /zh-tw/advanced/protected-tags                    /zh-tw/usage/access-control/protected-tags/ 301
 /zh-tw/advanced/repo-indexer                      /zh-tw/administration/repo-indexer/ 301
 /zh-tw/advanced/repo-mirror                       /zh-tw/usage/repository/repo-mirror/ 301
 /zh-tw/advanced/search-engines-indexation         /zh-tw/administration/search-engines-indexation/ 301
 /zh-tw/advanced/signing                           /zh-tw/administration/signing/ 301
 /zh-tw/developers/api-usage                       /zh-tw/development/api-usage/ 301
 /zh-tw/developers/integrations                    /zh-tw/development/integrations/ 301
 /zh-tw/developers/migrations-interfaces           /zh-tw/development/migrations-interfaces/ 301
 /zh-tw/developers/oauth2-provider                 /zh-tw/development/oauth2-provider/ 301
 /zh-tw/development                                /zh-tw/category/development/ 301
 /zh-tw/development/                               /zh-tw/category/development/ 301
 /zh-tw/features/authentication                    /zh-tw/administration/authentication/ 301
 /zh-tw/features/comparison                        /zh-tw/installation/comparison/ 301
 /zh-tw/features/webhooks                          /zh-tw/usage/repository/webhooks/ 301
 /zh-tw/help                                       /zh-tw/category/help/ 301
 /zh-tw/help/                                      /zh-tw/category/help/ 301
 /zh-tw/help/seek-help                             /zh-tw/help/support/ 301
 /zh-tw/installation                               /zh-tw/category/installation/ 301
 /zh-tw/installation/                              /zh-tw/category/installation/ 301
 /zh-tw/installation/upgrade-from-gogs             /zh-tw/category/installation/ 301
 /zh-tw/upgrade/upgrade-from-gitea                 /zh-tw/installation/upgrade-from-gitea/ 301
 /zh-tw/upgrade/upgrade-from-gogs                  /zh-tw/category/installation/ 301
 /zh-tw/usage                                      /zh-tw/category/usage/ 301
 /zh-tw/usage/                                     /zh-tw/category/usage/ 301
 /zh-tw/usage/actions/act-runner                   /runner/ 301
 /zh-tw/usage/agit-setup                           /zh-tw/usage/issues-prs/agit/ 301
 /zh-tw/usage/authentication                       /zh-tw/administration/authentication/ 301
 /zh-tw/usage/automatically-linked-references      /zh-tw/usage/issues-prs/automatically-linked-references/ 301
 /zh-tw/usage/badge                                /zh-tw/usage/actions/badge/ 301
 /zh-tw/usage/blame                                /zh-tw/usage/repository/blame/ 301
 /zh-tw/usage/blocking-user                        /zh-tw/usage/access-control/blocking-user/ 301
 /zh-tw/usage/clone-filters                        /zh-tw/usage/repository/clone-filters/ 301
 /zh-tw/usage/code-owners                          /zh-tw/usage/repository/code-owners/ 301
 /zh-tw/usage/command-line                         /zh-tw/administration/command-line/ 301
 /zh-tw/usage/email-setup                          /zh-tw/administration/email-setup/ 301
 /zh-tw/usage/git-lfs-setup                        /zh-tw/administration/git-lfs-setup/ 301
 /zh-tw/usage/https-setup                          /zh-tw/administration/https-setup/ 301
 /zh-tw/usage/incoming-email                       /zh-tw/usage/repository/incoming-email/ 301
 /zh-tw/usage/issue-pull-request-templates         /zh-tw/usage/issues-prs/issue-pull-request-templates/ 301
 /zh-tw/usage/labels                               /zh-tw/usage/issues-prs/labels/ 301
 /zh-tw/usage/markdown                             /zh-tw/usage/repository/markdown/ 301
 /zh-tw/usage/merge-message-templates              /zh-tw/usage/issues-prs/merge-message-templates/ 301
 /zh-tw/usage/migration                            /zh-tw/usage/repository/migration/ 301
 /zh-tw/usage/multi-factor-authentication          /zh-tw/usage/user-setting/multi-factor-authentication/ 301
 /zh-tw/usage/permissions                          /zh-tw/usage/access-control/permissions/ 301
 /zh-tw/usage/protected-tags                       /zh-tw/usage/access-control/protected-tags/ 301
 /zh-tw/usage/pull-request                         /zh-tw/usage/issues-prs/pull-request/ 301
 /zh-tw/usage/push                                 /zh-tw/usage/repository/push/ 301
 /zh-tw/usage/push-options                         /zh-tw/usage/repository/push/ 301
 /zh-tw/usage/push-to-create                       /zh-tw/usage/repository/push/ 301
 /zh-tw/usage/repo-mirror                          /zh-tw/usage/repository/repo-mirror/ 301
 /zh-tw/usage/secrets                              /zh-tw/usage/actions/secrets/ 301
 /zh-tw/usage/template-repositories                /zh-tw/usage/repository/template-repositories/ 301
 /zh-tw/usage/webhooks                             /zh-tw/usage/repository/webhooks/ 301
 # ... and under the develop version.
 /next/actions                                     /next/usage/actions/ 301
 /next/actions/                                    /next/usage/actions/ 301
 /next/administration                              /next/category/administration/ 301
 /next/administration/                             /next/category/administration/ 301
 /next/administration/logging-configuration        /next/administration/logging-config/ 301
 /next/advanced/adding-legal-pages                 /next/administration/adding-legal-pages/ 301
 /next/advanced/clone-filters                      /next/usage/repository/clone-filters/ 301
 /next/advanced/cmd-embedded                       /next/administration/cmd-embedded/ 301
 /next/advanced/config-cheat-sheet                 /next/administration/config-cheat-sheet/ 301
 /next/advanced/customizing-gitea                  /next/administration/customizing-gitea/ 301
 /next/advanced/environment-variables              /next/administration/environment-variables/ 301
 /next/advanced/external-renderers                 /next/administration/external-renderers/ 301
 /next/advanced/logging-configuration              /next/administration/logging-config/ 301
 /next/advanced/mail-templates                     /next/administration/mail-templates/ 301
 /next/advanced/protected-tags                     /next/usage/access-control/protected-tags/ 301
 /next/advanced/repo-indexer                       /next/administration/repo-indexer/ 301
 /next/advanced/repo-mirror                        /next/usage/repository/repo-mirror/ 301
 /next/advanced/search-engines-indexation          /next/administration/search-engines-indexation/ 301
 /next/advanced/signing                            /next/administration/signing/ 301
 /next/developers/api-usage                        /next/development/api-usage/ 301
 /next/developers/integrations                     /next/development/integrations/ 301
 /next/developers/migrations-interfaces            /next/development/migrations-interfaces/ 301
 /next/developers/oauth2-provider                  /next/development/oauth2-provider/ 301
 /next/development                                 /next/category/development/ 301
 /next/development/                                /next/category/development/ 301
 /next/features/authentication                     /next/administration/authentication/ 301
 /next/features/comparison                         /next/installation/comparison/ 301
 /next/features/webhooks                           /next/usage/repository/webhooks/ 301
 /next/help                                        /next/category/help/ 301
 /next/help/                                       /next/category/help/ 301
 /next/help/seek-help                              /next/help/support/ 301
 /next/installation                                /next/category/installation/ 301
 /next/installation/                               /next/category/installation/ 301
 /next/installation/upgrade-from-gogs              /next/category/installation/ 301
 /next/upgrade/upgrade-from-gitea                  /next/installation/upgrade-from-gitea/ 301
 /next/upgrade/upgrade-from-gogs                   /next/category/installation/ 301
 /next/usage                                       /next/category/usage/ 301
 /next/usage/                                      /next/category/usage/ 301
 /next/usage/actions/act-runner                    /runner/ 301
 /next/usage/agit                                  /next/usage/issues-prs/agit/ 301
 /next/usage/agit-setup                            /next/usage/issues-prs/agit/ 301
 /next/usage/authentication                        /next/administration/authentication/ 301
 /next/usage/automatically-linked-references       /next/usage/issues-prs/automatically-linked-references/ 301
 /next/usage/badge                                 /next/usage/actions/badge/ 301
 /next/usage/blame                                 /next/usage/repository/blame/ 301
 /next/usage/blocking-user                         /next/usage/access-control/blocking-user/ 301
 /next/usage/clone-filters                         /next/usage/repository/clone-filters/ 301
 /next/usage/code-owners                           /next/usage/repository/code-owners/ 301
 /next/usage/command-line                          /next/administration/command-line/ 301
 /next/usage/email-setup                           /next/administration/email-setup/ 301
 /next/usage/git-lfs-setup                         /next/administration/git-lfs-setup/ 301
 /next/usage/https-setup                           /next/administration/https-setup/ 301
 /next/usage/incoming-email                        /next/usage/repository/incoming-email/ 301
 /next/usage/issue-pull-request-templates          /next/usage/issues-prs/issue-pull-request-templates/ 301
 /next/usage/labels                                /next/usage/issues-prs/labels/ 301
 /next/usage/markdown                              /next/usage/repository/markdown/ 301
 /next/usage/merge-message-templates               /next/usage/issues-prs/merge-message-templates/ 301
 /next/usage/migration                             /next/usage/repository/migration/ 301
 /next/usage/multi-factor-authentication           /next/usage/user-setting/multi-factor-authentication/ 301
 /next/usage/permissions                           /next/usage/access-control/permissions/ 301
 /next/usage/profile-readme                        /next/usage/repository/profile-readme/ 301
 /next/usage/protected-tags                        /next/usage/access-control/protected-tags/ 301
 /next/usage/pull-request                          /next/usage/issues-prs/pull-request/ 301
 /next/usage/push                                  /next/usage/repository/push/ 301
 /next/usage/push-options                          /next/usage/repository/push/ 301
 /next/usage/push-to-create                        /next/usage/repository/push/ 301
 /next/usage/repo-mirror                           /next/usage/repository/repo-mirror/ 301
 /next/usage/secrets                               /next/usage/actions/secrets/ 301
 /next/usage/template-repositories                 /next/usage/repository/template-repositories/ 301
 /next/usage/webhooks                              /next/usage/repository/webhooks/ 301
 # ... and under simplified chinese, develop.
 /zh-cn/next/actions                               /zh-cn/next/usage/actions/ 301
 /zh-cn/next/actions/                              /zh-cn/next/usage/actions/ 301
 /zh-cn/next/administration                        /zh-cn/next/category/administration/ 301
 /zh-cn/next/administration/                       /zh-cn/next/category/administration/ 301
 /zh-cn/next/administration/logging-configuration  /zh-cn/next/administration/logging-config/ 301
 /zh-cn/next/advanced/adding-legal-pages           /zh-cn/next/administration/adding-legal-pages/ 301
 /zh-cn/next/advanced/clone-filters                /zh-cn/next/usage/repository/clone-filters/ 301
 /zh-cn/next/advanced/cmd-embedded                 /zh-cn/next/administration/cmd-embedded/ 301
 /zh-cn/next/advanced/config-cheat-sheet           /zh-cn/next/administration/config-cheat-sheet/ 301
 /zh-cn/next/advanced/customizing-gitea            /zh-cn/next/administration/customizing-gitea/ 301
 /zh-cn/next/advanced/environment-variables        /zh-cn/next/administration/environment-variables/ 301
 /zh-cn/next/advanced/external-renderers           /zh-cn/next/administration/external-renderers/ 301
 /zh-cn/next/advanced/logging-configuration        /zh-cn/next/administration/logging-config/ 301
 /zh-cn/next/advanced/mail-templates               /zh-cn/next/administration/mail-templates/ 301
 /zh-cn/next/advanced/protected-tags               /zh-cn/next/usage/access-control/protected-tags/ 301
 /zh-cn/next/advanced/repo-indexer                 /zh-cn/next/administration/repo-indexer/ 301
 /zh-cn/next/advanced/repo-mirror                  /zh-cn/next/usage/repository/repo-mirror/ 301
 /zh-cn/next/advanced/search-engines-indexation    /zh-cn/next/administration/search-engines-indexation/ 301
 /zh-cn/next/advanced/signing                      /zh-cn/next/administration/signing/ 301
 /zh-cn/next/developers/api-usage                  /zh-cn/next/development/api-usage/ 301
 /zh-cn/next/developers/integrations               /zh-cn/next/development/integrations/ 301
 /zh-cn/next/developers/migrations-interfaces      /zh-cn/next/development/migrations-interfaces/ 301
 /zh-cn/next/developers/oauth2-provider            /zh-cn/next/development/oauth2-provider/ 301
 /zh-cn/next/development                           /zh-cn/next/category/development/ 301
 /zh-cn/next/development/                          /zh-cn/next/category/development/ 301
 /zh-cn/next/features/authentication               /zh-cn/next/administration/authentication/ 301
 /zh-cn/next/features/comparison                   /zh-cn/next/installation/comparison/ 301
 /zh-cn/next/features/webhooks                     /zh-cn/next/usage/repository/webhooks/ 301
 /zh-cn/next/help                                  /zh-cn/next/category/help/ 301
 /zh-cn/next/help/                                 /zh-cn/next/category/help/ 301
 /zh-cn/next/help/seek-help                        /zh-cn/next/help/support/ 301
 /zh-cn/next/installation                          /zh-cn/next/category/installation/ 301
 /zh-cn/next/installation/                         /zh-cn/next/category/installation/ 301
 /zh-cn/next/installation/upgrade-from-gogs        /zh-cn/next/category/installation/ 301
 /zh-cn/next/upgrade/upgrade-from-gitea            /zh-cn/next/installation/upgrade-from-gitea/ 301
 /zh-cn/next/upgrade/upgrade-from-gogs             /zh-cn/next/category/installation/ 301
 /zh-cn/next/usage                                 /zh-cn/next/category/usage/ 301
 /zh-cn/next/usage/                                /zh-cn/next/category/usage/ 301
 /zh-cn/next/usage/actions/act-runner              /runner/ 301
 /zh-cn/next/usage/agit-setup                      /zh-cn/next/usage/issues-prs/agit/ 301
 /zh-cn/next/usage/authentication                  /zh-cn/next/administration/authentication/ 301
 /zh-cn/next/usage/automatically-linked-references /zh-cn/next/usage/issues-prs/automatically-linked-references/ 301
 /zh-cn/next/usage/badge                           /zh-cn/next/usage/actions/badge/ 301
 /zh-cn/next/usage/blame                           /zh-cn/next/usage/repository/blame/ 301
 /zh-cn/next/usage/blocking-user                   /zh-cn/next/usage/access-control/blocking-user/ 301
 /zh-cn/next/usage/clone-filters                   /zh-cn/next/usage/repository/clone-filters/ 301
 /zh-cn/next/usage/code-owners                     /zh-cn/next/usage/repository/code-owners/ 301
 /zh-cn/next/usage/command-line                    /zh-cn/next/administration/command-line/ 301
 /zh-cn/next/usage/email-setup                     /zh-cn/next/administration/email-setup/ 301
 /zh-cn/next/usage/git-lfs-setup                   /zh-cn/next/administration/git-lfs-setup/ 301
 /zh-cn/next/usage/https-setup                     /zh-cn/next/administration/https-setup/ 301
 /zh-cn/next/usage/incoming-email                  /zh-cn/next/usage/repository/incoming-email/ 301
 /zh-cn/next/usage/issue-pull-request-templates    /zh-cn/next/usage/issues-prs/issue-pull-request-templates/ 301
 /zh-cn/next/usage/labels                          /zh-cn/next/usage/issues-prs/labels/ 301
 /zh-cn/next/usage/markdown                        /zh-cn/next/usage/repository/markdown/ 301
 /zh-cn/next/usage/merge-message-templates         /zh-cn/next/usage/issues-prs/merge-message-templates/ 301
 /zh-cn/next/usage/migration                       /zh-cn/next/usage/repository/migration/ 301
 /zh-cn/next/usage/multi-factor-authentication     /zh-cn/next/usage/user-setting/multi-factor-authentication/ 301
 /zh-cn/next/usage/permissions                     /zh-cn/next/usage/access-control/permissions/ 301
 /zh-cn/next/usage/profile-readme                  /zh-cn/next/usage/repository/profile-readme/ 301
 /zh-cn/next/usage/protected-tags                  /zh-cn/next/usage/access-control/protected-tags/ 301
 /zh-cn/next/usage/pull-request                    /zh-cn/next/usage/issues-prs/pull-request/ 301
 /zh-cn/next/usage/push                            /zh-cn/next/usage/repository/push/ 301
 /zh-cn/next/usage/push-options                    /zh-cn/next/usage/repository/push/ 301
 /zh-cn/next/usage/push-to-create                  /zh-cn/next/usage/repository/push/ 301
 /zh-cn/next/usage/repo-mirror                     /zh-cn/next/usage/repository/repo-mirror/ 301
 /zh-cn/next/usage/secrets                         /zh-cn/next/usage/actions/secrets/ 301
 /zh-cn/next/usage/template-repositories           /zh-cn/next/usage/repository/template-repositories/ 301
 /zh-cn/next/usage/webhooks                        /zh-cn/next/usage/repository/webhooks/ 301
 # ... and under traditional chinese, develop.
 /zh-tw/next/actions                               /zh-tw/next/usage/actions/ 301
 /zh-tw/next/actions/                              /zh-tw/next/usage/actions/ 301
 /zh-tw/next/administration                        /zh-tw/next/category/administration/ 301
 /zh-tw/next/administration/                       /zh-tw/next/category/administration/ 301
 /zh-tw/next/administration/logging-configuration  /zh-tw/next/administration/logging-config/ 301
 /zh-tw/next/advanced/adding-legal-pages           /zh-tw/next/administration/adding-legal-pages/ 301
 /zh-tw/next/advanced/clone-filters                /zh-tw/next/usage/repository/clone-filters/ 301
 /zh-tw/next/advanced/cmd-embedded                 /zh-tw/next/administration/cmd-embedded/ 301
 /zh-tw/next/advanced/config-cheat-sheet           /zh-tw/next/administration/config-cheat-sheet/ 301
 /zh-tw/next/advanced/customizing-gitea            /zh-tw/next/administration/customizing-gitea/ 301
 /zh-tw/next/advanced/environment-variables        /zh-tw/next/administration/environment-variables/ 301
 /zh-tw/next/advanced/external-renderers           /zh-tw/next/administration/external-renderers/ 301
 /zh-tw/next/advanced/logging-configuration        /zh-tw/next/administration/logging-config/ 301
 /zh-tw/next/advanced/mail-templates               /zh-tw/next/administration/mail-templates/ 301
 /zh-tw/next/advanced/protected-tags               /zh-tw/next/usage/access-control/protected-tags/ 301
 /zh-tw/next/advanced/repo-indexer                 /zh-tw/next/administration/repo-indexer/ 301
 /zh-tw/next/advanced/repo-mirror                  /zh-tw/next/usage/repository/repo-mirror/ 301
 /zh-tw/next/advanced/search-engines-indexation    /zh-tw/next/administration/search-engines-indexation/ 301
 /zh-tw/next/advanced/signing                      /zh-tw/next/administration/signing/ 301
 /zh-tw/next/developers/api-usage                  /zh-tw/next/development/api-usage/ 301
 /zh-tw/next/developers/integrations               /zh-tw/next/development/integrations/ 301
 /zh-tw/next/developers/migrations-interfaces      /zh-tw/next/development/migrations-interfaces/ 301
 /zh-tw/next/developers/oauth2-provider            /zh-tw/next/development/oauth2-provider/ 301
 /zh-tw/next/development                           /zh-tw/next/category/development/ 301
 /zh-tw/next/development/                          /zh-tw/next/category/development/ 301
 /zh-tw/next/features/authentication               /zh-tw/next/administration/authentication/ 301
 /zh-tw/next/features/comparison                   /zh-tw/next/installation/comparison/ 301
 /zh-tw/next/features/webhooks                     /zh-tw/next/usage/repository/webhooks/ 301
 /zh-tw/next/help                                  /zh-tw/next/category/help/ 301
 /zh-tw/next/help/                                 /zh-tw/next/category/help/ 301
 /zh-tw/next/help/seek-help                        /zh-tw/next/help/support/ 301
 /zh-tw/next/installation                          /zh-tw/next/category/installation/ 301
 /zh-tw/next/installation/                         /zh-tw/next/category/installation/ 301
 /zh-tw/next/installation/upgrade-from-gogs        /zh-tw/next/category/installation/ 301
 /zh-tw/next/upgrade/upgrade-from-gitea            /zh-tw/next/installation/upgrade-from-gitea/ 301
 /zh-tw/next/upgrade/upgrade-from-gogs             /zh-tw/next/category/installation/ 301
 /zh-tw/next/usage                                 /zh-tw/next/category/usage/ 301
 /zh-tw/next/usage/                                /zh-tw/next/category/usage/ 301
 /zh-tw/next/usage/actions/act-runner              /runner/ 301
 /zh-tw/next/usage/agit-setup                      /zh-tw/next/usage/issues-prs/agit/ 301
 /zh-tw/next/usage/authentication                  /zh-tw/next/administration/authentication/ 301
 /zh-tw/next/usage/automatically-linked-references /zh-tw/next/usage/issues-prs/automatically-linked-references/ 301
 /zh-tw/next/usage/badge                           /zh-tw/next/usage/actions/badge/ 301
 /zh-tw/next/usage/blame                           /zh-tw/next/usage/repository/blame/ 301
 /zh-tw/next/usage/blocking-user                   /zh-tw/next/usage/access-control/blocking-user/ 301
 /zh-tw/next/usage/clone-filters                   /zh-tw/next/usage/repository/clone-filters/ 301
 /zh-tw/next/usage/code-owners                     /zh-tw/next/usage/repository/code-owners/ 301
 /zh-tw/next/usage/command-line                    /zh-tw/next/administration/command-line/ 301
 /zh-tw/next/usage/email-setup                     /zh-tw/next/administration/email-setup/ 301
 /zh-tw/next/usage/git-lfs-setup                   /zh-tw/next/administration/git-lfs-setup/ 301
 /zh-tw/next/usage/https-setup                     /zh-tw/next/administration/https-setup/ 301
 /zh-tw/next/usage/incoming-email                  /zh-tw/next/usage/repository/incoming-email/ 301
 /zh-tw/next/usage/issue-pull-request-templates    /zh-tw/next/usage/issues-prs/issue-pull-request-templates/ 301
 /zh-tw/next/usage/labels                          /zh-tw/next/usage/issues-prs/labels/ 301
 /zh-tw/next/usage/markdown                        /zh-tw/next/usage/repository/markdown/ 301
 /zh-tw/next/usage/merge-message-templates         /zh-tw/next/usage/issues-prs/merge-message-templates/ 301
 /zh-tw/next/usage/migration                       /zh-tw/next/usage/repository/migration/ 301
 /zh-tw/next/usage/multi-factor-authentication     /zh-tw/next/usage/user-setting/multi-factor-authentication/ 301
 /zh-tw/next/usage/permissions                     /zh-tw/next/usage/access-control/permissions/ 301
 /zh-tw/next/usage/protected-tags                  /zh-tw/next/usage/access-control/protected-tags/ 301
 /zh-tw/next/usage/pull-request                    /zh-tw/next/usage/issues-prs/pull-request/ 301
 /zh-tw/next/usage/push                            /zh-tw/next/usage/repository/push/ 301
 /zh-tw/next/usage/push-options                    /zh-tw/next/usage/repository/push/ 301
 /zh-tw/next/usage/push-to-create                  /zh-tw/next/usage/repository/push/ 301
 /zh-tw/next/usage/repo-mirror                     /zh-tw/next/usage/repository/repo-mirror/ 301
 /zh-tw/next/usage/secrets                         /zh-tw/next/usage/actions/secrets/ 301
 /zh-tw/next/usage/template-repositories           /zh-tw/next/usage/repository/template-repositories/ 301
 /zh-tw/next/usage/webhooks                        /zh-tw/next/usage/repository/webhooks/ 301
 # Runner versions that were published under their full number, and the develop
 # runner docs, which used to be `next`.
 /runner/0.2.11/* /runner/0/:splat 301
 /runner/1.0.8/* /runner/1/:splat 301
 /runner/next/* /runner/develop/:splat 301
@@ -0,0 +1,32 @@
 {
  "_comment": "Algolia DocSearch crawler configuration. The three facets come from the docsearch:* meta tags every page carries; only the versions people read are indexed, the older ones stay reachable through the version picker.",
  "index_name": "gitea",
  "start_urls": [
    "https://docs.gitea.com/",
    "https://docs.gitea.com/next/",
    "https://docs.gitea.com/zh-cn/",
    "https://docs.gitea.com/zh-tw/",
    "https://docs.gitea.com/runner/",
    "https://docs.gitea.com/api/",
    "https://docs.gitea.com/enterprise/"
  ],
  "sitemap_urls": ["https://docs.gitea.com/sitemap-index.xml"],
  "exclusion_patterns": [
    "https://docs.gitea.com/1.2*/**",
    "https://docs.gitea.com/*/1.2*/**",
    "https://docs.gitea.com/api/1.2*/**",
    "https://docs.gitea.com/runner/[0-9]/**"
  ],
  "selectors": {
    "lvl0": { "selector": "//nav[contains(@aria-labelledby,'starlight__sidebar')]//a[@aria-current='page']/ancestor::details//summary//span", "type": "xpath", "global": true, "default_value": "Documentation" },
    "lvl1": ".sl-markdown-content h1, h1",
    "lvl2": ".sl-markdown-content h2",
    "lvl3": ".sl-markdown-content h3",
    "lvl4": ".sl-markdown-content h4",
    "text": ".sl-markdown-content p, .sl-markdown-content li, .sl-markdown-content td"
  },
  "custom_settings": {
    "attributesForFaceting": ["product", "version", "language"]
  },
  "conversation_id": []
 }
@@ -1,49 +0,0 @@
 ---
 date: "2023-05-25T00:00:00+00:00"
 title: "重构指南"
 slug: "guidelines-refactoring"
 sidebar_position: 20
 toc: false
 draft: false
 aliases:
  - /zh-cn/guidelines-refactoring
 menu:
  sidebar:
    parent: "contributing"
    name: "重构指南"
    sidebar_position: 20
    identifier: "guidelines-refactoring"
 ---
 # 重构指南
 ## 背景
 自2014年2月12日编写了第一行代码以来，Gitea已经发展成为一个庞大的项目。
 因此，代码库变得越来越大。代码库越大，维护就越困难。
 存在许多过时的机制，许多框架混合在一起，一些遗留代码可能会导致错误并阻碍新功能的开发。
 为了使代码库更易于维护，使Gitea变得更好，开发人员应牢记使用现代机制来重构旧代码。
 本文档是关于重构代码库的指南集合。
 ## 重构建议
 * 设计更多关于未来的内容，而不仅仅解决当前问题。
 * 减少模糊性，减少冲突，提高可维护性。
 * 描述重构，例如：
  * 为什么需要重构。
  * 如何解决旧问题。
  * 重构的优点/缺点是什么。
 * 只做必要的更改，尽量保留旧逻辑。
 * 引入一些中间步骤，使重构更容易审查，完整的重构计划可以在几个PR中完成。
 * 如果存在分歧，应该请TOC（技术监督委员会）参与决策。
 * 添加必要的测试以确保重构的正确性。
 * 非错误重构优先在里程碑的开始时进行，这样可以更容易地在发布之前发现问题。
 ## 审查和合并建议
 * 重构的PR不应该长时间保持打开状态（通常为7天），应尽快进行审查。
 * 重构的PR应尽快合并，不应被其他PR阻塞。
 * 如果TOC没有异议，重构的PR可以在7天后由一名核心成员（非作者）批准后合并。
 * 如果最终结果良好，容忍一些不完美/临时的步骤。
 * 如果重构是必要的，容忍一些回归错误，并尽快修复错误。
@@ -1,64 +0,0 @@
 ---
 date: "2021-01-22T00:00:00+02:00"
 title: "Übersetzungs Richtlinien"
 slug: "localization"
 sidebar_position: 70
 toc: false
 draft: false
 menu:
  sidebar:
    parent: "contributing"
    name: "Übersetzungsrichtlinien"
    sidebar_position: 70
    identifier: "localization"
 ---
 ## Allgemeines
 Anrede: Wenig förmlich:
 * "Du"-Form
 * Keine "Amtsdeusch"-Umschreibungen, einfach so als ob man den Nutzer direkt persönlich ansprechen würde
 Genauer definiert:
 * "falsch" anstatt "nicht korrekt/inkorrekt"
 * Benutzerkonto oder Konto? Oder Account?
 * "Wende dich an ..." anstatt "kontaktiere ..."
 * In der selben Zeit übersetzen (sonst wird aus "is" "war")
 * Richtige Anführungszeichen verwenden. Also `"` statt `''` oder `'` oder \` oder `´`
  * `„` für beginnende Anführungszeichen, `“` für schließende Anführungszeichen
 Es gelten Artikel und Worttrennungen aus dem Duden.
 ## Formulierungen in Modals und Buttons
 Es sollten die gleichen Formulierungen auf Buttons und Modals verwendet werden.
 Beispiel: Wenn der Button mit `löschen` beschriftet ist, sollte im Modal die Frage lauten `Willst du das wirklich löschen?` und nicht `Willst du das wirklich entfernen?`. Gleiches gilt für Success/Errormeldungen nach der Aktion.
 ## Trennungen
 * Pull-Request
 * Time-Tracker
 * E-Mail-Adresse (siehe Duden)
 ## Artikeldefinitionen für Anglizismen
 * _Der_ Commit (m.)
 * _Der_ Branch (m.), plural: die Branches
 * _Das_ Issue (n.)
 * _Der_ Fork (m.)
 * _Das_ Repository (n.), plural: die Repositories
 * _Der_ Pull-Request (m.)
 * _Der_ Token (m.), plural: die Token
 * _Das_ Review (n.)
 * _Der_ Key (m.)
 * _Der_ Committer (m.), plural: die Committer
 ## Weiterführende Links
 Diese beiden Links sind sehr empfehlenswert:
 * http://docs.translatehouse.org/projects/localization-guide/en/latest/guide/translation_guidelines_german.html
 * https://docs.qgis.org/2.18/en/docs/documentation_guidelines/do_translations.html
@@ -1,17 +0,0 @@
 ---
 date: "2023-05-25T00:00:00+02:00"
 title: "翻译指南"
 sidebar_position: 70
 toc: true
 draft: false
 menu:
  sidebar:
    parent: "contributing"
    name: "翻译指南"
    sidebar_position: 70
    identifier: "translation-guidelines"
 ---
 本页面用于提供一套通用规则，以确保翻译的一致性。
 * [German](/de-de/übersetzungs-richtlinien/)
@@ -1,40 +0,0 @@
 ---
 date: "2023-05-25T17:29:00+08:00"
 title: "迁移界面"
 slug: "migrations-interfaces"
 sidebar_position: 55
 toc: false
 draft: false
 aliases:
  - /zh-cn/migrations-interfaces
 menu:
  sidebar:
    parent: "development"
    name: "迁移界面"
    sidebar_position: 55
    identifier: "migrations-interfaces"
 ---
 # 迁移功能
 完整迁移功能在Gitea 1.9.0版本中引入。它定义了两个接口，用于支持从其他Git托管平台迁移存储库数据到Gitea，或者在将来将Gitea数据迁移到其他Git托管平台。
 目前已实现了从GitHub、GitLab和其他Gitea实例的迁移。
 首先，Gitea在包[modules/migration](https://github.com/go-gitea/gitea/tree/main/modules/migration)中定义了一些标准对象。它们是`Repository`、`Milestone`、`Release`、`ReleaseAsset`、`Label`、`Issue`、`Comment`、`PullRequest`、`Reaction`、`Review`、`ReviewComment`。
 ## 下载器接口
 要从新的Git托管平台迁移，需要进行两个步骤的更新。
 - 您应该实现一个`Downloader`，用于获取存储库信息。
 - 您应该实现一个`DownloaderFactory`，用于检测URL是否匹配，并创建上述的`Downloader`。
  - 您需要在`init()`中通过`RegisterDownloaderFactory`注册`DownloaderFactory`。
 您可以在[downloader.go](https://github.com/go-gitea/gitea/blob/main/modules/migration/downloader.go)中找到这些接口。
 ## 上传器接口
 目前，只实现了`GiteaLocalUploader`，因此我们只能通过此Uploader将下载的数据保存到本地的Gitea实例。目前不支持其他上传器。
 您可以在[uploader.go](https://github.com/go-gitea/gitea/blob/main/modules/migration/uploader.go)中找到这些接口。
@@ -1,137 +0,0 @@
 ---
 date: "2019-04-19:44:00+01:00"
 title: "OAuth2 提供者"
 slug: "oauth2-provider"
 sidebar_position: 41
 toc: false
 draft: false
 aliases:
  - /zh-cn/oauth2-provider
 menu:
  sidebar:
    parent: "development"
    name: "OAuth2 提供者"
    sidebar_position: 41
    identifier: "oauth2-provider"
 ---
 # OAuth2 提供者
 Gitea 支持作为 OAuth2 提供者，允许第三方应用程序在用户同意的情况下访问其资源。此功能自 1.8.0 版起可用。
 ## 端点
 | 端点                     | URL                                 |
 | ------------------------ | ----------------------------------- |
 | OpenID Connect Discovery | `/.well-known/openid-configuration` |
 | Authorization Endpoint   | `/login/oauth/authorize`            |
 | Access Token Endpoint    | `/login/oauth/access_token`         |
 | OpenID Connect UserInfo  | `/login/oauth/userinfo`             |
 | JSON Web Key Set         | `/login/oauth/keys`                 |
 ## 支持的 OAuth2 授权
 目前 Gitea 仅支持 [**Authorization Code Grant**](https://tools.ietf.org/html/rfc6749#section-1.3.1) 标准，并额外支持以下扩展：
 - [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636)
 - [OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth)
 要将 Authorization Code Grant 作为第三方应用程序，您需要通过在设置中添加一个新的 "应用程序" (`/user/settings/applications`)。
 ## 范围
 Gitea 支持以下令牌范围:
 | 名称 | 介绍 |
 | ---- | ----------- |
 | **(no scope)** | 授予对公共用户配置文件和公共存储库的只读访问权限 |
 | **repo** | 完全控制所有存储库 |
 | &nbsp;&nbsp;&nbsp; **repo:status** | 授予对所有存储库中提交状态的读/写访问权限 |
 | &nbsp;&nbsp;&nbsp; **public_repo** | 仅授予对公共存储库的读/写访问权限 |
 | **admin:repo_hook** | 授予对所有存储库的 Hooks 访问权限，该权限已包含在 `repo` 范围中 |
 | &nbsp;&nbsp;&nbsp; **write:repo_hook** | 授予对存储库 Hooks 的读/写访问权限 |
 | &nbsp;&nbsp;&nbsp; **read:repo_hook** | 授予对存储库 Hooks 的只读访问权限 |
 | **admin:org** | 授予对组织设置的完全访问权限 |
 | &nbsp;&nbsp;&nbsp; **write:org** | 授予对组织设置的读/写访问权限 |
 | &nbsp;&nbsp;&nbsp; **read:org** | 授予对组织设置的只读访问权限 |
 | **admin:public_key** | 授予公钥管理的完全访问权限 |
 | &nbsp;&nbsp;&nbsp; **write:public_key** | 授予对公钥的读/写访问权限 |
 | &nbsp;&nbsp;&nbsp; **read:public_key** | 授予对公钥的只读访问权限 |
 | **admin:org_hook** | 授予对组织级别 Hooks 的完全访问权限 |
 | **admin:user_hook** | 授予对用户级别 Hooks 的完全访问权限 |
 | **notification** | 授予对通知的完全访问权限 |
 | **user** | 授予对用户个人资料信息的完全访问权限 |
 | &nbsp;&nbsp;&nbsp; **read:user** | 授予对用户个人资料的读取权限 |
 | &nbsp;&nbsp;&nbsp; **user:email** | 授予对用户电子邮件地址的读取权限 |
 | &nbsp;&nbsp;&nbsp; **user:follow** | 授予访问权限以关注/取消关注用户 |
 | **delete_repo** | 授予删除存储库的权限 |
 | **package** | 授予对托管包的完全访问权限 |
 | &nbsp;&nbsp;&nbsp; **write:package** | 授予对包的读/写访问权限 |
 | &nbsp;&nbsp;&nbsp; **read:package** | 授予对包的读取权限 |
 | &nbsp;&nbsp;&nbsp; **delete:package** | 授予对包的删除权限 |
 | **admin:gpg_key** | 授予 GPG 密钥管理的完全访问权限 |
 | &nbsp;&nbsp;&nbsp; **write:gpg_key** | 授予对 GPG 密钥的读/写访问权限 |
 | &nbsp;&nbsp;&nbsp; **read:gpg_key** | 授予对 GPG 密钥的只读访问权限 |
 | **admin:application** | 授予应用程序管理的完全访问权限 |
 | &nbsp;&nbsp;&nbsp; **write:application** | 授予应用程序管理的读/写访问权限 |
 | &nbsp;&nbsp;&nbsp; **read:application** | 授予应用程序管理的读取权限 |
 | **sudo** | 允许以站点管理员身份执行操作 |
 ## 客户端类型
 Gitea 支持私密和公共客户端类型，[参见 RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1).
 对于公共客户端, 允许在本地回环地址的重定向 URI 中使用任意端口，例如 `http://127.0.0.1/`。根据 [RFC 8252 的建议](https://datatracker.ietf.org/doc/html/rfc8252#section-8.3)，请避免使用 `localhost`。
 ## 示例
 **注意：** 该示例中尚未使用 PKCE。
 1. 将用户重定向到授权端点，以获得他们的访问资源授权:
   ```curl
   https://[YOUR-GITEA-URL]/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI& response_type=code&state=STATE
   ```
   在设置中注册应用程序以获得 `CLIENT_ID`。`STATE` 是一个随机字符串，它将在获得用户授权后发送回您的应用程序。`state` 参数是可选的，但您应该使用它来防止 CSRF 攻击。
   ![Authorization Page](/authorize.png)
   用户将会被询问是否授权给您的应用程序。如果他们同意了授权，用户将会被重定向到 `REDIRECT_URL`，例如：
   ```curl
   https://[REDIRECT_URI]?code=RETURNED_CODE&state=STATE
   ```
 2. 使用重定向提供的 `code`，您可以请求一个新的应用程序和 Refresh Token。Access Token Endpoint 接受 `application/json` 或 `application/x-www-form-urlencoded` 类型的 POST 请求，例如：
   ```curl
   POST https://[YOUR-GITEA-URL]/login/oauth/access_token
   ```
   ```json
   {
     "client_id": "YOUR_CLIENT_ID",
     "client_secret": "YOUR_CLIENT_SECRET",
     "code": "RETURNED_CODE",
     "grant_type": "authorization_code",
     "redirect_uri": "REDIRECT_URI"
   }
   ```
   返回：
   ```json
   {
     "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjowLCJleHAiOjE1NTUxNzk5MTIsImlhdCI6MTU1NTE3NjMxMn0.0-iFsAwBtxuckA0sNZ6QpBQmywVPz129u75vOM7wPJecw5wqGyBkmstfJHAjEOqrAf_V5Z-1QYeCh_Cz4RiKug",
     "token_type": "bearer",
     "expires_in": 3600,
     "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjoxLCJjbnQiOjEsImV4cCI6MTU1NzgwNDMxMiwiaWF0IjoxNTU1MTc2MzEyfQ.S_HZQBy4q9r5SEzNGNIoFClT43HPNDbUdHH-GYNYYdkRfft6XptJBkUQscZsGxOW975Yk6RbgtGvq1nkEcklOw"
   }
   ```
   `CLIENT_SECRET` 是生成给应用程序的唯一密钥。请注意，该密钥只会在您使用 Gitea 创建/注册应用程序后出现一次。如果您丢失了密钥，您必须在应用程序设置中重新生成密钥。
   `access_token` 请求中的 `REDIRECT_URI` 必须与 `authorize` 请求中的 `REDIRECT_URI` 相符。
 3. 使用 `access_token` 来构造 [API 请求](development/api-usage.md#oauth2-provider) 以读写用户的资源。
@@ -0,0 +1,9 @@
 {
  "label": "Administration",
  "position": 30,
  "link": {
    "type": "generated-index",
    "slug": "/administration",
    "title": "Administration"
  }
 }
@@ -0,0 +1,33 @@
 ---
 date: "2019-12-28"
 slug: adding-legal-pages
 sidebar_position: 110
 aliases:
  - /en-us/adding-legal-pages
 ---
 # Adding Legal Pages
 Some jurisdictions (such as EU), requires certain legal pages (e.g. Privacy Policy) to be added to website. Follow these steps to add them to your Gitea instance.
 ## Getting Pages
 Gitea source code ships with sample pages, available in `contrib/service/sample-page` directory. Copy them to `custom/public/assets/`. For example, to add Privacy Policy:
 ```bash
 wget -O /path/to/custom/public/assets/privacy.html https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/service/sample-page/privacy.html.sample
 ```
 Now you need to edit the page to meet your requirements. In particular you must change the email addresses, web addresses and references to "Your Gitea Instance" to match your situation.
 You absolutely must not place a general ToS or privacy statement that implies that the Gitea project is responsible for your server.
 ## Make it Visible
 Create or append to `/path/to/custom/templates/custom/extra_links_footer.tmpl`:
 ```go
 <a class="item" href="{{AppSubUrl}}/assets/privacy.html">Privacy Policy</a>
 ```
 Restart Gitea to see the changes.
@@ -0,0 +1,434 @@
 ---
 date: "2016-12-01T16:00:00+02:00"
 slug: "authentication"
 sidebar_position: 10
 aliases:
  - /en-us/authentication
 ---
 # Authentication
 ## LDAP (Lightweight Directory Access Protocol)
 Both the LDAP via BindDN and the simple auth LDAP share the following fields:
 - Authorization Name **(required)**
  - A name to assign to the new method of authorization.
 - Host **(required)**
  - The address where the LDAP server can be reached.
  - Example: `mydomain.com`
 - Port **(required)**
  - The port to use when connecting to the server.
  - Example: `389` for LDAP or `636` for LDAP SSL
 - Enable TLS Encryption (optional)
  - Whether to use TLS when connecting to the LDAP server.
 - Admin Filter (optional)
  - An LDAP filter specifying if a user should be given administrator
    privileges. If a user account passes the filter, the user will be
    privileged as an administrator.
  - Example: `(objectClass=adminAccount)`
  - Example for Microsoft Active Directory (AD): `(memberOf=CN=admin-group,OU=example,DC=example,DC=org)`
 - Username attribute (optional)
  - The attribute of the user's LDAP record containing the user name. Given
    attribute value will be used for new Gitea account user name after first
    successful sign-in. Leave empty to use login name given on sign-in form.
  - This is useful when supplied login name is matched against multiple
    attributes, but only single specific attribute should be used for Gitea
    account name, see "User Filter".
  - Example: `uid`
  - Example for Microsoft Active Directory (AD): `sAMAccountName`
 - First name attribute (optional)
  - The attribute of the user's LDAP record containing the user's first name.
    This will be used to populate their account information.
  - Example: `givenName`
 - Surname attribute (optional)
  - The attribute of the user's LDAP record containing the user's surname.
    This will be used to populate their account information.
  - Example: `sn`
 - E-mail attribute **(required)**
  - The attribute of the user's LDAP record containing the user's email
    address. This will be used to populate their account information.
  - Example: `mail`
 ### LDAP via BindDN
 Adds the following fields:
 - Bind DN (optional)
  - The DN to bind to the LDAP server with when searching for the user. This
    may be left blank to perform an anonymous search.
  - Example: `cn=Search,dc=mydomain,dc=com`
 - Bind Password (optional)
  - The password for the Bind DN specified above, if any. _Note: The password
    is stored encrypted with the SECRET_KEY on the server. It is still recommended
    to ensure that the Bind DN has as few privileges as possible._
 - User Search Base **(required)**
  - The LDAP base at which user accounts will be searched for.
  - Example: `ou=Users,dc=mydomain,dc=com`
 - User Filter **(required)**
  - An LDAP filter declaring how to find the user record that is attempting to
    authenticate. The `%[1]s` matching parameter will be substituted with login
    name given on sign-in form.
  - Example: `(&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))`
  - Example for Microsoft Active Directory (AD): `(&(objectCategory=Person)(memberOf=CN=user-group,OU=example,DC=example,DC=org)(sAMAccountName=%s)(!(UserAccountControl:1.2.840.113556.1.4.803:=2)))`
  - To substitute more than once, `%[1]s` should be used instead, e.g. when
    matching supplied login name against multiple attributes such as user
    identifier, email or even phone number.
  - Example: `(&(objectClass=Person)(|(uid=%[1]s)(mail=%[1]s)(mobile=%[1]s)))`
 - Enable user synchronization
  - This option enables a periodic task that synchronizes the Gitea users with
    the LDAP server. The default period is every 24 hours but that can be
    changed in the app.ini file. See the _cron.sync_external_users_ section in
    the [sample
    app.ini](https://github.com/go-gitea/gitea/blob/main/custom/conf/app.example.ini)
    for detailed comments about that section. The _User Search Base_ and _User
    Filter_ settings described above will limit which users can use Gitea and
    which users will be synchronized. When initially run the task will create
    all LDAP users that match the given settings so take care if working with
    large Enterprise LDAP directories.
 ### LDAP using simple auth
 Adds the following fields:
 - User DN **(required)**
  - A template to use as the user's DN. The `%s` matching parameter will be
    substituted with login name given on sign-in form.
  - Example: `cn=%s,ou=Users,dc=mydomain,dc=com`
  - Example: `uid=%s,ou=Users,dc=mydomain,dc=com`
 - User Search Base (optional)
  - The LDAP base at which user accounts will be searched for.
  - Example: `ou=Users,dc=mydomain,dc=com`
 - User Filter **(required)**
  - An LDAP filter declaring when a user should be allowed to log in. The `%[1]s`
    matching parameter will be substituted with login name given on sign-in
    form.
  - Example: `(&(objectClass=posixAccount)(|(cn=%[1]s)(mail=%[1]s)))`
  - Example: `(&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))`
 ### Verify group membership in LDAP
 Uses the following fields:
 - Group Search Base DN (optional)
  - The LDAP DN used for groups.
  - Example: `ou=group,dc=mydomain,dc=com`
 - Group Attribute Containing List Of Users (optional)
  - The attribute of the group object that lists/contains the group members.
  - Example: `memberUid` or `member`
 - User Attribute Listed in Group (optional)
  - The user attribute that is used to reference a user in the group object.
  - Example: `uid` if the group objects contains a `member: bender` and the user object contains a `uid: bender`.
  - Example: `dn` if the group object contains a `member: uid=bender,ou=users,dc=planetexpress,dc=com`.
 - Verify group membership in LDAP (optional)
  - An LDAP filter declaring how to find valid groups in the above DN.
  - Example: `(|(cn=gitea_users)(cn=admins))`
 ## PAM (Pluggable Authentication Module)
 This procedure enables PAM authentication.  Users may still be added to the
 system manually using the user administration.  PAM provides a mechanism to
 automatically add users to the current database by testing them against PAM
 authentication.  To work with normal Linux passwords, the user running Gitea
 must also have read access to `/etc/shadow` in order to check the validity of
 the account when logging in using a public key.
 **Note**: If a user has added SSH public keys into Gitea, the use of these
 keys _may_ bypass the login check system.  Therefore, if you wish to disable a user who
 authenticates with PAM, you _should_ also manually disable the account in Gitea using the
 built-in user manager.
 1. Configure and prepare the installation.
    - It is recommended that you create an administrative user.
    - Deselecting automatic sign-up may also be desired.
 1. Once the database has been initialized, log in as the newly created
 administrative user.
 1. Navigate to the user setting (icon in top-right corner), and select
 `Site Administration` -> `Authentication Sources`, and select
 `Add Authentication Source`.
 1. Fill out the field as follows:
    - `Authentication Type` : `PAM`
    - `Name` : Any value should be valid here, use "System Authentication" if
    you'd like.
    - `PAM Service Name` : Select the appropriate file listed under `/etc/pam.d/`
    that performs the authentication desired.[^1]
    - `PAM Email Domain` : The e-mail suffix to append to user authentication.
    For example, if the login system expects a user called `gituser`, and this
    field is set to `mail.com`, then Gitea will expect the `user email` field
    for an authenticated GIT instance to be `[email protected]`.[^2]
 **Note**: PAM support is added via [build-time flags](installation/from-source.md#build),
 and the official binaries provided do not have this enabled.  PAM requires that
 the necessary libpam dynamic library be available and the necessary PAM
 development headers be accessible to the compiler.
 [^1]: For example, using standard Linux log-in on Debian "Bullseye" use
 `common-session-noninteractive` - this value may be valid for other flavors of
 Debian including Ubuntu and Mint, consult your distribution's documentation.
 [^2]: **This is a required field for PAM**.  Be aware: In the above example, the
 user will log into the Gitea web interface as `gituser` and not `[email protected]`
 ## SMTP (Simple Mail Transfer Protocol)
 This option allows Gitea to log in to an SMTP host as a Gitea user. To
 configure this, set the fields below:
 - Authentication Name **(required)**
  - A name to assign to the new method of authorization.
 - SMTP Authentication Type **(required)**
  - Type of authentication to use to connect to SMTP host, PLAIN or LOGIN.
 - Host **(required)**
  - The address where the SMTP host can be reached.
  - Example: `smtp.mydomain.com`
 - Port **(required)**
  - The port to use when connecting to the server.
  - Example: `587`
 - Allowed Domains
  - Restrict what domains can log in if using a public SMTP host or SMTP host
    with multiple domains.
  - Example: `gitea.com,mydomain.com,mydomain2.com`
 - Force SMTPS
  - SMTPS will be used by default for connections to port 465, if you wish to use SMTPS
  for other ports. Set this value.
  - Otherwise if the server provides the `STARTTLS` extension this will be used.
 - Skip TLS Verify
  - Disable TLS verify on authentication.
 - This Authentication Source is Activated
  - Enable or disable this authentication source.
 ## FreeIPA
 - In order to log in to Gitea using FreeIPA credentials, a bind account needs to
  be created for Gitea:
 - On the FreeIPA server, create a `gitea.ldif` file, replacing `dc=example,dc=com`
  with your DN, and provide an appropriately secure password:
  ```sh
  dn: uid=gitea,cn=sysaccounts,cn=etc,dc=example,dc=com
  changetype: add
  objectclass: account
  objectclass: simplesecurityobject
  uid: gitea
  userPassword: secure password
  passwordExpirationTime: 20380119031407Z
  nsIdleTimeout: 0
  ```
 - Import the LDIF (change localhost to an IPA server if needed). A prompt for
  Directory Manager password will be presented:
  ```sh
  ldapmodify -h localhost -p 389 -x -D \
  "cn=Directory Manager" -W -f gitea.ldif
  ```
 - Add an IPA group for gitea_users :
  ```sh
  ipa group-add --desc="Gitea Users" gitea_users
  ```
 - Note: For errors about IPA credentials, run `kinit admin` and provide the
  domain admin account password.
 - Log in to Gitea as an Administrator and click on "Authentication" under Admin Panel.
  Then click `Add New Source` and fill in the details, changing all where appropriate.
 ## SPNEGO with SSPI (Kerberos/NTLM, for Windows only)
 Gitea supports SPNEGO single sign-on authentication (the scheme defined by RFC4559) for the web part of the server via the Security Support Provider Interface (SSPI) built in Windows. SSPI works only in Windows environments - when both the server and the clients are running Windows.
 Before activating SSPI single sign-on authentication (SSO) you have to prepare your environment:
 - Create a separate user account in active directory, under which the `gitea.exe` process will be running (eg. `user` under domain `domain.local`):
 - Create a service principal name for the host where `gitea.exe` is running with class `HTTP`:
  - Start `Command Prompt` or `PowerShell` as a privileged domain user (eg. Domain Administrator)
  - Run the command below, replacing `host.domain.local` with the fully qualified domain name (FQDN) of the server where the web application will be running, and `domain\user` with the name of the account created in the previous step:
  ```sh
  setspn -A HTTP/host.domain.local domain\user
  ```
 - Sign in (_sign out if you were already signed in_) with the user created
 - Make sure that `ROOT_URL` in the `[server]` section of `custom/conf/app.ini` is the fully qualified domain name of the server where the web application will be running - the same you used when creating the service principal name (eg. `host.domain.local`)
 - Start the web server (`gitea.exe web`)
 - Enable SSPI authentication by adding an `SPNEGO with SSPI` authentication source in `Site Administration -> Authentication Sources`
 - Sign in to a client computer in the same domain with any domain user (client computer, different from the server running `gitea.exe`)
 - If you are using Chrome or Edge, add the URL of the web app to the Local intranet sites (`Internet Options -> Security -> Local intranet -> Sites`)
 - Start Chrome or Edge and navigate to the FQDN URL of Gitea (eg. `http://host.domain.local:3000`)
 - Click the `Sign In` button on the dashboard and choose SSPI to be automatically logged in with the same user that is currently logged on to the computer
 - If it does not work, make sure that:
  - You are not running the web browser on the same server where Gitea is running. You should be running the web browser on a domain joined computer (client) that is different from the server. If both the client and server are running on the same computer NTLM will be preferred over Kerberos.
  - There is only one `HTTP/...` SPN for the host
  - The SPN contains only the hostname, without the port
  - You have added the URL of the web app to the `Local intranet zone`
  - The clocks of the server and client should not differ with more than 5 minutes (depends on group policy)
  - `Integrated Windows Authentication` should be enabled in Internet Explorer (under `Advanced settings`)
 ## Reverse Proxy
 Gitea supports Reverse Proxy Header authentication, it will read headers as a trusted login user name or user email address. This hasn't been enabled by default, you can enable it with
 ```ini
 [service]
 ENABLE_REVERSE_PROXY_AUTHENTICATION = true
 ```
 The default login user name is in the `X-WEBAUTH-USER` header, you can change it via changing `REVERSE_PROXY_AUTHENTICATION_USER` in app.ini. If the user doesn't exist, you can enable automatic registration with `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION=true`.
 The default login user email is `X-WEBAUTH-EMAIL`, you can change it via changing `REVERSE_PROXY_AUTHENTICATION_EMAIL` in app.ini, this could also be disabled with `ENABLE_REVERSE_PROXY_EMAIL`
 If set `ENABLE_REVERSE_PROXY_FULL_NAME=true`, a user full name expected in `X-WEBAUTH-FULLNAME` will be assigned to the user when auto creating the user. You can also change the header name with `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`.
 You can also limit the reverse proxy's IP address range with `REVERSE_PROXY_TRUSTED_PROXIES` which default value is `127.0.0.0/8,::1/128`. By `REVERSE_PROXY_LIMIT`, you can limit trusted proxies level.
 You can enable the this authentication method for the API with
 ```ini
 [service]
 ENABLE_REVERSE_PROXY_AUTHENTICATION_API = true
 ```
 :::note
 When this method is enabled for the API, the reverse proxy is responsible for handling CSRF protection.
 :::
 ## OAuth2 and OpenID Connect
 Gitea can delegate the login to an external OAuth2 or OpenID Connect provider,
 which is what "Sign in with ..." on the login page uses. This is the client side
 of the protocol; for the other direction, using a Gitea instance as the provider
 for another application, see
 [Gitea as an OAuth2 provider](../development/oauth2-provider.md).
 A source is added under `Site Administration -> Identity & Access ->
 Authentication Sources -> Add Authentication Source`, with `OAuth2` as the
 authentication type, or on the command line with
 `gitea admin auth add-oauth`. The fields are:
 - **Authentication Name (required)**
  - The name of the source. It is part of the callback URL, so it cannot be
    changed later without registering a new callback URL at the provider.
 - **OAuth2 Provider (required)**
  - `OpenID Connect` for any provider that implements OpenID Connect discovery
    (Keycloak, Authentik, Authelia, Entra ID, Okta, Zitadel and others), or one
    of the providers Gitea knows about directly: Gitea, GitHub, GitLab, Google,
    Discord, Bitbucket, Dropbox, Facebook, Mastodon, Nextcloud, Twitter, Yandex
    and Azure AD v2.
 - **Client ID (Key)** and **Client Secret (required)**
  - The credentials of the application registered at the provider.
 - **OpenID Connect Auto Discovery URL**
  - Only for the `OpenID Connect` provider: the discovery document of the
    provider, usually `https://provider.example.com/.well-known/openid-configuration`.
    Gitea reads the endpoints from it.
 - **Additional Scopes**
  - Scopes to request on top of the ones the provider needs by default. For
    OpenID Connect, `openid` is always added, and the scopes are taken from
    `OPENID_CONNECT_SCOPES` in `app.ini` when it is set.
 - **Required Claim Name** and **Required Claim Value**
  - Restrict the login to accounts whose token carries this claim, optionally
    with this exact value.
 - **Claim name providing group names**, **Group Claim value for administrator
  users**, **Group Claim value for restricted users** and **Map claimed groups
  to Organization teams**
  - Grant the administrator or the restricted flag, and organization team
    membership, from the groups the provider reports. They all need the claim
    name to be set.
 - **Icon URL**
  - Image shown next to the button on the login page.
 Register `{ROOT_URL}/user/oauth2/{Authentication Name}/callback` as the
 redirect URI at the provider, for example
 `https://gitea.example.com/user/oauth2/keycloak/callback` for a source named
 `keycloak`. A wrong redirect URI is the most common reason for the login to
 fail at the provider.
 What happens to accounts that log in this way is configured in `app.ini`, see
 [OAuth2 Client](config-cheat-sheet.md#oauth2-client-oauth2_client):
 ```ini title="app.ini"
 [oauth2_client]
 ; create an account for a user who logs in for the first time
 ENABLE_AUTO_REGISTRATION = true
 ; where the username of a new account comes from
 USERNAME = nickname
 ; what to do when the username or email is already taken
 ACCOUNT_LINKING = login
 ```
 :::note
 This is unrelated to `ENABLE_OPENID_SIGNIN` and the `[openid]` section, which
 configure the older OpenID 2.0 sign-in.
 :::
@@ -0,0 +1,176 @@
 ---
 date: "2017-01-01T16:00:00+02:00"
 slug: "backup-and-restore"
 sidebar_position: 11
 aliases:
  - /en-us/backup-and-restore
 ---
 # Backup and Restore
 Gitea currently has a `dump` command that will save the installation to a ZIP file. This
 file can be unpacked and used to restore an instance.
 ## Backup Consistency
 To ensure the consistency of the Gitea instance, it must be shutdown during backup.
 Gitea consists of a database, files and git repositories, all of which change when it is used. For instance, when a migration is in progress, a transaction is created in the database while the git repository is being copied over. If the backup happens in the middle of the migration, the git repository may be incomplete although the database claims otherwise because it was dumped afterwards. The only way to avoid such race conditions is by stopping the Gitea instance during the backups.
 ## Backup Command (`dump`)
 Switch to the user running Gitea: `su git`. Run `./gitea dump -c /path/to/app.ini` in the Gitea installation
 directory. There should be some output similar to the following:
 ```log
 2016/12/27 22:32:09 Creating tmp work dir: /tmp/gitea-dump-417443001
 2016/12/27 22:32:09 Dumping local repositories.../home/git/repositories
 2016/12/27 22:32:22 Dumping database...
 2016/12/27 22:32:22 Packing dump files...
 2016/12/27 22:32:34 Removing tmp work dir: /tmp/gitea-dump-417443001
 2016/12/27 22:32:34 Finish dumping in file gitea-dump-1482906742.zip
 ```
 Inside the `gitea-dump-1482906742.zip` file, will be the following:
 - `app.ini` - Optional copy of configuration file if originally stored outside the default `custom/` directory
 - `custom/` - All config or customization files in `custom/`.
 - `data/` - Data directory (APP_DATA_PATH), except sessions if you are using file session. This directory includes `attachments`, `avatars`, `lfs`, `indexers`, SQLite file if you are using SQLite.
 - `repos/` - Complete copy of the repository directory.
 - `gitea-db.sql` - SQL dump of database
 - `log/` - Various logs. They are not needed for a recovery or migration.
 Intermediate backup files are created in a temporary directory specified either with the
 `--tempdir` command-line parameter or the `TMPDIR` environment variable.
 ## Backup the database
 The SQL dump created by `gitea dump` uses XORM and Gitea admins may prefer to use the native the MySQL and PostgreSQL dump tools instead. There are still open issues when using XORM for dumping the database that may cause problems when attempting to restore it.
 ```sh
 # mysql
 mysqldump -u$USER -p$PASS --database $DATABASE > gitea-db.sql
 # postgres
 pg_dump -U $USER $DATABASE > gitea-db.sql
 ```
 ### Using Docker (`dump`)
 There are a few caveats for using the `dump` command with Docker.
 The command has to be executed with the `RUN_USER = <OS_USERNAME>` specified in `gitea/conf/app.ini`; and, for the zipping of the backup folder to occur without permission error the command `docker exec` must be executed inside of the `--tempdir`.
 Example:
 ```bash
 docker exec -u <OS_USERNAME> -it -w <--tempdir> $(docker ps -qf 'name=^<NAME_OF_DOCKER_CONTAINER>$') bash -c '/usr/local/bin/gitea dump -c </path/to/app.ini>'
 ```
 \*Note: `--tempdir` refers to the temporary directory of the docker environment used by Gitea; if you have not specified a custom `--tempdir`, then Gitea uses `/tmp` or the `TMPDIR` environment variable of the docker container. For `--tempdir` adjust your `docker exec` command options accordingly.
 The result should be a file, stored in the `--tempdir` specified, along the lines of: `gitea-dump-1482906742.zip`
 ## Restore Command (`restore`)
 There is currently no support for a recovery command. It is a manual process that mostly
 involves moving files to their correct locations and restoring a database dump.
 Example:
 ```sh
 unzip gitea-dump-1610949662.zip
 cd gitea-dump-1610949662
 mv app.ini /etc/gitea/conf/app.ini
 mv data/* /var/lib/gitea/data/
 mv log/* /var/lib/gitea/log/
 mv repos/* /var/lib/gitea/data/repositories/
 chown -R gitea:gitea /etc/gitea/conf/app.ini /var/lib/gitea
 # mysql
 mysql --default-character-set=utf8mb4 -u$USER -p$PASS $DATABASE <gitea-db.sql
 # sqlite3
 sqlite3 $DATABASE_PATH <gitea-db.sql
 # postgres
 psql -U $USER -d $DATABASE < gitea-db.sql
 service gitea restart
 ```
 Repository Git Hooks should be regenerated if installation method is changed (eg. binary -> Docker), or if Gitea is installed to a different directory than the previous installation.
 With Gitea running, and from the directory Gitea's binary is located, execute: `./gitea admin regenerate hooks`
 This ensures that application and configuration file paths in repository Git Hooks are consistent and applicable to the current installation. If these paths are not updated, repository `push` actions will fail.
 If you still have issues, consider running `./gitea doctor check` to inspect possible errors (or run with `--fix`).
 ### Using Docker (`restore`)
 There is also no support for a recovery command in a Docker-based gitea instance. The restore process contains the same steps as described in the previous section but with different paths.
 Example:
 ```sh
 # open bash session in container
 docker exec --user git -it 2a83b293548e bash
 # unzip your backup file within the container
 unzip gitea-dump-1610949662.zip
 cd gitea-dump-1610949662
 # restore the gitea data
 mv data/* /data/gitea
 # restore the repositories itself
 mv repos/* /data/git/repositories/
 # adjust file permissions
 chown -R git:git /data
 # Regenerate Git Hooks
 /usr/local/bin/gitea -c '/data/gitea/conf/app.ini' admin regenerate hooks
 ```
 The default user in the gitea container is `git` (1000:1000). Please replace `2a83b293548e` with your gitea container id or name.
 ### Using Docker-rootless (`restore`)
 The restore workflow in Docker-rootless containers differs only in the directories to be used:
 ```sh
 # open bash session in container
 docker exec --user git -it 2a83b293548e bash
 # unzip your backup file within the container
 unzip gitea-dump-1610949662.zip
 cd gitea-dump-1610949662
 # restore the app.ini
 mv data/conf/app.ini /etc/gitea/app.ini
 # restore the gitea data
 mv data/* /var/lib/gitea
 # restore the repositories itself
 mv repos/* /var/lib/gitea/git/repositories
 # adjust file permissions
 chown -R git:git /etc/gitea/app.ini /var/lib/gitea
 # Regenerate Git Hooks
 /usr/local/bin/gitea -c '/etc/gitea/app.ini' admin regenerate hooks
 ```
 ### Using `gitea dump` to convert database types
 The `gitea dump` command can produce a SQL file that can be read by another database type, which is useful to convert the database to another in case you did not choose the correct one during the first installation.
 Note that this conversion process is not well-tested, which is why it is recommended to choose the final database type during the first installation without attempting to change it afterwards.
 Stop the Gitea server, then make sure you have a full backup of your original database.
 Before attempting the conversion, ensure that the original database is clean. Run `gitea doctor check --all --fix` and `gitea doctor recreate-table` to address common issues.
 Use the `--database` flag to get a Gitea dump with the SQL file in the target format, in this example PostgreSQL: `gitea dump --database postgres`, then extract the file `gitea-db.sql` from the generated ZIP file.
 Create the PostgreSQL Gitea user and Gitea database. Then, import the SQL file as the Gitea user into the Gitea database, using commands such as:
 ```sh
 sudo -u postgres psql -d gitea
 gitea=# SET synchronous_commit TO off
 gitea=# SET on_error_stop TO on
 gitea=# \i gitea-db.sql
 ```
 Disabling `synchronous_commit` makes PostgreSQL less resilient to crashes, but makes the import a lot faster. Since we already have a backup of the original database and we can check that the import completes successfully, it should be a good trade-off.
 After the import is completed, set up Gitea to use PostgreSQL and start the Gitea server again. Good luck!
@@ -1,30 +1,23 @@
 ---
 date: "2020-01-25T21:00:00-03:00"
 title: "Embedded data extraction tool"
 slug: "cmd-embedded"
 sidebar_position: 20
 toc: false
 draft: false
 aliases:
  - /en-us/cmd-embedded
 menu:
  sidebar:
    parent: "administration"
    name: "Embedded data extraction tool"
    sidebar_position: 20
    identifier: "cmd-embedded"
 ---
 # Embedded data extraction tool
 Gitea's executable contains all the resources required to run: templates, images, style-sheets
 and translations. Any of them can be overridden by placing a replacement in a matching path
-inside the `custom` directory (see [Customizing Gitea](administration/customizing-gitea.md)).
+inside the `custom` directory (see [Customizing Gitea](../administration/customizing-gitea.md)).
 To obtain a copy of the embedded resources ready for editing, the `embedded` command from the CLI
 can be used from the OS shell interface.
-**NOTE:** The embedded data extraction tool is included in Gitea versions 1.12 and above.
+:::note
 The embedded data extraction tool is included in Gitea versions 1.12 and above.
 :::
 ## Listing resources
@@ -83,7 +76,7 @@ The default is the current directory.
 The `--custom` flag tells Gitea to extract the files directly into the `custom` directory.
 For this to work, the command needs to know the location of the `app.ini` configuration
 file (`--config`) and, depending of the configuration, be ran from the directory where
-Gitea normally starts. See [Customizing Gitea](administration/customizing-gitea.md) for details.
+Gitea normally starts. See [Customizing Gitea](../administration/customizing-gitea.md) for details.
 The `--overwrite` flag allows any existing files in the destination directory to be overwritten.
@@ -0,0 +1,120 @@
 ---
 date: "2019-10-15T10:10:00+05:00"
 slug: "email-setup"
 sidebar_position: 12
 aliases:
  - /en-us/email-setup
 ---
 # Email setup
 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.
 :::note
 For use in the official Gitea Docker image, please configure with the SMTP version (see the following section).
 :::
 :::note
 For Internet-facing sites consult documentation of your MTA for instructions to send emails over TLS. Also set up SPF, DMARC, and DKIM DNS records to make emails sent be accepted as legitimate by various email providers.
 :::
 ```ini title="app.ini"
 [mailer]
 ENABLED       = true
 FROM          = gitea@mydomain.com
 PROTOCOL      = sendmail
 SENDMAIL_PATH = /usr/sbin/sendmail
 SENDMAIL_ARGS = "--" ; most "sendmail" programs take options, "--" will prevent an email address being interpreted as an option.
 ```
 ## Using SMTP
 Directly use SMTP server as relay. This option is useful if you don't want to set up MTA on your instance but you have an account at email provider.
 ```ini title="app.ini"
 [mailer]
 ENABLED        = true
 FROM           = gitea@mydomain.com
 PROTOCOL       = smtps
 SMTP_ADDR      = mail.mydomain.com
 SMTP_PORT      = 465
 USER           = gitea@mydomain.com
 PASSWD         = `password`
 ```
 Restart Gitea for the configuration changes to take effect.
 To send a test email to validate the settings, go to Gitea > Site Administration > Configuration > Summary -> Mailer Configuration.
 For the full list of options check the [Config Cheat Sheet](../administration/config-cheat-sheet.md)
 :::note
 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 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.
 Note that Implicit TLS is recommended by [RFC8314](https://tools.ietf.org/html/rfc8314#section-3) since 2018.
 ### Gmail
 The following configuration should work with GMail's SMTP server:
 ```ini title="app.ini"
 [mailer]
 ENABLED        = true
 HOST           = smtp.gmail.com:465 ; Remove this line for Gitea >= 1.18.0
 SMTP_ADDR      = smtp.gmail.com
 SMTP_PORT      = 465
 FROM           = example.user@gmail.com
 USER           = example.user
 PASSWD         = `***`
 PROTOCOL       = smtps
 ```
 Note that you'll need to create and use an [App password](https://support.google.com/accounts/answer/185833?hl=en) by enabling 2FA on your Google
 account. You won't be able to use your Google account password directly.
 ### ProtonMail
 This feature is currently only available for select Proton for Business customers and those with Visionary and Family plans with custom domain addresses. See [ProtonMail's SMTP documentation](https://proton.me/support/smtp-submission) for more information. This limitation can be circumvented by using the ProtonMail Bridge application.
 Note that emails sent using SMTP are not [end-to-end encrypted](https://proton.me/support/proton-mail-encryption-explained). However, they’re still stored with zero-access encryption like any other emails in your Proton Mail inbox.
 The following configuration should work with ProtonMail's SMTP server:
 1. In your browser (or desktop application), sign in to your Proton Mail account and select **Settings → All settings → Proton Mail → IMAP/SMTP → SMTP tokens**.
 2. Click **Generate token**.
 3. Enter the following details to create a new SMTP token:
    - **Token name**: Select a name for your token. This is for your reference only and does not affect the token's functionality.
    - **Email address**: Select one of your active custom domain addresses to pair with your token. Copy this email address and use it for the `FROM` and `USER` configuration in `app.ini`.
 4. Click **Generate**.
 5. Enter your Proton Mail Account password.
 Your SMTP username and SMTP token (password) will be generated. You can now enter them as the `USER` and `PASSWD` in your `app.ini` configuration.
 ```ini title="app.ini"
 [mailer]
 ENABLED        = true
 FROM           = example.user@customdomain.tld
 PROTOCOL       = smtp+starttls
 SMTP_ADDR      = smtp.protonmail.ch
 SMTP_PORT      = 587
 USER           = example.user@customdomain.tld
 PASSWD         = `TOKEN`
 ```
 After closing the popup, you will not be able to see this SMTP token (password) again for security reasons. You can always generate more tokens if you need to rotate passwords.
 Note: Your Proton Mail login or mailbox passwords will not work with SMTP
@@ -1,18 +1,9 @@
 ---
 date: "2017-04-08T11:34:00+02:00"
 title: "Environment variables"
 slug: "environment-variables"
 sidebar_position: 10
 toc: false
 draft: false
 aliases:
  - /en-us/environment-variables
 menu:
  sidebar:
    parent: "administration"
    name: "Environment variables"
    sidebar_position: 10
    identifier: "environment-variables"
 ---
 # Environment variables
@@ -1,21 +1,12 @@
 ---
 date: "2018-11-23:00:00+02:00"
 title: "External renderers"
 slug: "external-renderers"
 sidebar_position: 60
 toc: false
 draft: false
 aliases:
  - /en-us/external-renderers
 menu:
  sidebar:
    parent: "administration"
    name: "External renderers"
    sidebar_position: 60
    identifier: "external-renderers"
 ---
-# Custom files rendering configuration
+# External renderers
 Gitea supports custom file renderings (i.e., Jupyter notebooks, asciidoc, etc.) through external binaries,
 it is just a matter of:
@@ -24,7 +15,7 @@ it is just a matter of:
 - add some configuration to your `app.ini` file
 - restart your Gitea instance
-This supports rendering of whole files. If you want to render code blocks in markdown you would need to do something with javascript. See some examples on the [Customizing Gitea](administration/customizing-gitea.md) page.
+This supports rendering of whole files. If you want to render code blocks in markdown you would need to do something with javascript. See some examples on the [Customizing Gitea](../administration/customizing-gitea.md) page.
 ## Installing external binaries
@@ -32,18 +23,16 @@ 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 gitea/gitea:@version@
+FROM docker.gitea.com/gitea:@dockerVersion@
 [...]
 COPY custom/app.ini /data/gitea/conf/app.ini
 [...]
-RUN apk --no-cache add asciidoctor freetype freetype-dev gcc g++ libpng libffi-dev py-pip python3-dev py3-pip py3-pyzmq
+RUN apk --no-cache add asciidoctor freetype freetype-dev gcc g++ libpng libffi-dev pandoc python3-dev py3-pyzmq pipx
 # install any other package you need for your external renderers
-RUN pip3 install --upgrade pip
+RUN pipx install jupyter docutils --include-deps --global
 RUN pip3 install -U setuptools
 RUN pip3 install jupyter docutils
 # add above any other python package you may need to install
 ```
@@ -0,0 +1,118 @@
 ---
 date: "2018-05-11T11:00:00+02:00"
 slug: "fail2ban-setup"
 sidebar_position: 16
 aliases:
  - /en-us/fail2ban-setup
 ---
 # Fail2ban Setup
 **Remember that fail2ban is powerful and can cause lots of issues if you do it incorrectly, so make
 sure to test this before relying on it so you don't lock yourself out.**
 Gitea returns an HTTP 200 for bad logins in the web logs, but if you have logging options on in
 `app.ini`, then you should be able to go off of `log/gitea.log`, which gives you something like this
 on a bad authentication from the web or CLI using SSH or HTTP respectively:
 ```log
 2018/04/26 18:15:54 [I] Failed authentication attempt for user from xxx.xxx.xxx.xxx
 ```
 ```log
 2020/10/15 16:05:09 modules/ssh/ssh.go:143:publicKeyHandler() [W] Failed authentication attempt from xxx.xxx.xxx.xxx
 ```
 (DEPRECATED: This may be a false positive as the user may still go on to correctly authenticate.)
 ```log
 2020/10/15 16:05:09 modules/ssh/ssh.go:155:publicKeyHandler() [W] Failed authentication attempt from xxx.xxx.xxx.xxx
 ```
 (DEPRECATED: This may be a false positive as the user may still go on to correctly authenticate.)
 ```log
 2020/10/15 16:05:09 modules/ssh/ssh.go:198:publicKeyHandler() [W] Failed authentication attempt from xxx.xxx.xxx.xxx
 ```
 (DEPRECATED: This may be a false positive as the user may still go on to correctly authenticate.)
 ```log
 2020/10/15 16:05:09 modules/ssh/ssh.go:213:publicKeyHandler() [W] Failed authentication attempt from xxx.xxx.xxx.xxx
 ```
 (DEPRECATED: This may be a false positive as the user may still go on to correctly authenticate.)
 ```log
 2020/10/15 16:05:09 modules/ssh/ssh.go:227:publicKeyHandler() [W] Failed authentication attempt from xxx.xxx.xxx.xxx
 ```
 (DEPRECATED: This may be a false positive as the user may still go on to correctly authenticate.)
 ```log
 2020/10/15 16:05:09 modules/ssh/ssh.go:249:sshConnectionFailed() [W] Failed authentication attempt from xxx.xxx.xxx.xxx
 ```
 (From 1.15 this new message will available and doesn't have any of the false positive results that above messages from publicKeyHandler do. This will only be logged if the user has completely failed authentication.)
 ```log
 2020/10/15 16:08:44 ...s/context/context.go:204:HandleText() [E] invalid credentials from xxx.xxx.xxx.xxx
 ```
 Add our filter in `/etc/fail2ban/filter.d/gitea.local`:
 ```ini
 # gitea.local
 [Definition]
 failregex =  .*(Failed authentication attempt|invalid credentials|Attempted access of unknown user).* from <HOST>
 ignoreregex =
 ```
 Add our jail in `/etc/fail2ban/jail.d/gitea.local`:
 ```ini
 [gitea]
 enabled = true
 filter = gitea
 logpath = /var/lib/gitea/log/gitea.log
 maxretry = 10
 findtime = 3600
 bantime = 900
 action = iptables-allports
 ```
 If you're using Docker, you'll also need to add an additional jail to handle the **FORWARD**
 chain in **iptables**. Configure it in `/etc/fail2ban/jail.d/gitea-docker.local`:
 ```ini
 [gitea-docker]
 enabled = true
 filter = gitea
 logpath = /var/lib/gitea/log/gitea.log
 maxretry = 10
 findtime = 3600
 bantime = 900
 action = iptables-allports[chain="FORWARD"]
 ```
 Then simply run `service fail2ban restart` to apply your changes. You can check to see if
 fail2ban has accepted your configuration using `service fail2ban status`.
 Make sure and read up on fail2ban and configure it to your needs, this bans someone
 for **15 minutes** (from all ports) when they fail authentication 10 times in an hour.
 If you run Gitea behind a reverse proxy with Nginx (for example with Docker), you need to add
 this to your Nginx configuration so that IPs don't show up as 127.0.0.1:
 ```
 proxy_set_header X-Real-IP $remote_addr;
 ```
 The security options in `app.ini` need to be adjusted to allow the interpretation of the headers
 as well as the list of IP addresses and networks that describe trusted proxy servers
 (See the [configuration cheat sheet](../administration/config-cheat-sheet.md#security-security) for more information).
 ```
 REVERSE_PROXY_LIMIT = 1
 REVERSE_PROXY_TRUSTED_PROXIES = 127.0.0.1/8 ; 172.17.0.0/16 for the docker default network
 ```
@@ -0,0 +1,43 @@
 ---
 date: "2019-10-06T08:00:00+05:00"
 slug: "git-lfs-setup"
 sidebar_position: 12
 aliases:
  - /en-us/git-lfs-setup
 ---
 # Git LFS setup
 To use Gitea's built-in LFS support, you must update the `app.ini` file:
 ```ini
 [server]
 ; Enables git-lfs support. true or false, default is false.
 LFS_START_SERVER = true
 [lfs]
 ; Where your lfs files reside, default is data/lfs.
 PATH = /home/gitea/data/lfs
 ```
 :::note
 LFS server support needs at least Git v2.1.2 installed on the server
 :::
 # Git LFS Pure SSH protocol
 The LFS Pure SSH protocol supports making LFS connections purely over SSH
 (without having to expose an HTTP endpoint for the Gitea server).
 Support for it can be enabled with the config option `server.LFS_ALLOW_PURE_SSH`:
 ```ini
 [server]
 LFS_ALLOW_PURE_SSH = true
 ```
 :::note
 The option is currently set to default false due to an open bug in the `git-lfs`
 client that causes SSH transfers to hang: https://github.com/git-lfs/git-lfs/pull/5816
 This can be worked around on all the client machines by setting the git config:
 `git config --global lfs.ssh.automultiplex false`
 :::
@@ -0,0 +1,115 @@
 ---
 date: "2018-06-02T11:00:00+02:00"
 slug: "https-setup"
 sidebar_position: 12
 aliases:
  - /en-us/https-setup
 ---
 # HTTPS Setup
 ## Using the built-in server
 Before you enable HTTPS, make sure that you have valid SSL/TLS certificates.
 You could use self-generated certificates for evaluation and testing. Please run `gitea cert --host [HOST]` to generate a self signed certificate.
 If you are using Apache or nginx on the server, it's recommended to check the [reverse proxy guide](./reverse-proxies.md).
 To use Gitea's built-in HTTPS support, you must change your `app.ini` file:
 ```ini
 [server]
 PROTOCOL  = https
 ROOT_URL  = https://git.example.com:3000/
 HTTP_PORT = 3000
 CERT_FILE = cert.pem
 KEY_FILE  = key.pem
 ```
 Note that if your certificate is signed by a third party certificate authority (i.e. not self-signed), then cert.pem should contain the certificate chain. The server certificate must be the first entry in cert.pem, followed by the intermediaries in order (if any). The root certificate does not have to be included because the connecting client must already have it in order to establish the trust relationship.
 To learn more about the config values, please checkout the [Config Cheat Sheet](./config-cheat-sheet.md#server-server).
 For the `CERT_FILE` or `KEY_FILE` field, the file path is relative to the `GITEA_CUSTOM` environment variable when it is a relative path. It can be an absolute path as well.
 ### Setting up HTTP redirection
 The Gitea server is only able to listen to one port; to redirect HTTP requests to the HTTPS port, you will need to enable the HTTP redirection service:
 ```ini
 [server]
 REDIRECT_OTHER_PORT = true
 ; Port the redirection service should listen on
 PORT_TO_REDIRECT = 3080
 ```
 If you are using Docker, make sure that this port is configured in your `docker-compose.yml` file.
 ## Using ACME (Default: Let's Encrypt)
 [ACME](https://tools.ietf.org/html/rfc8555) is a Certificate Authority standard protocol that allows you to automatically request and renew SSL/TLS certificates. [Let's Encrypt](https://letsencrypt.org/) is a free publicly trusted Certificate Authority server using this standard. Only `HTTP-01` and `TLS-ALPN-01` challenges are implemented. In order for ACME challenges to pass and verify your domain ownership, external traffic to the gitea domain on port `80` (`HTTP-01`) or port `443` (`TLS-ALPN-01`) has to be served by the gitea instance. Setting up [HTTP redirection](#setting-up-http-redirection) and port-forwards might be needed for external traffic to route correctly. Normal traffic to port `80` will otherwise be automatically redirected to HTTPS. **You must consent** to the ACME provider's terms of service (default Let's Encrypt's [terms of service](https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf)).
 Minimum setup using the default Let's Encrypt:
 ```ini
 [server]
 PROTOCOL=https
 DOMAIN=git.example.com
 ENABLE_ACME=true
 ACME_ACCEPTTOS=true
 ACME_DIRECTORY=https
 ;; Email can be omitted here and provided manually at first run, after which it is cached
 ACME_EMAIL=email@example.com
 ```
 Minimum setup using a [smallstep CA](https://github.com/smallstep/certificates), refer to [their tutorial](https://smallstep.com/docs/tutorials/acme-challenge) for more information.
 ```ini
 [server]
 PROTOCOL=https
 DOMAIN=git.example.com
 ENABLE_ACME=true
 ACME_ACCEPTTOS=true
 ACME_URL=https://ca.example.com/acme/acme/directory
 ;; Can be omitted if using the system's trust is preferred
 ;ACME_CA_ROOT=/path/to/root_ca.crt
 ACME_DIRECTORY=https
 ACME_EMAIL=email@example.com
 ```
 To learn more about the config values, please checkout the [Config Cheat Sheet](./config-cheat-sheet.md#server-server).
 :::warning
 `ACME_DIRECTORY` is where the account key and the issued certificates are
 cached, and the default `https` is a relative path, resolved against the working
 directory of the Gitea process. In the official Docker image that working
 directory is `/app/gitea`, which is part of the container and not of the `/data`
 volume, so every recreated container starts without an account and without
 certificates and asks the CA for new ones. Let's Encrypt allows
 [5 certificates per week](https://letsencrypt.org/docs/rate-limits/) for the
 same set of domains, after which the instance is left without a working
 certificate until the limit expires.
 Point the setting at a path inside the volume when running in a container:
 ```ini title="app.ini"
 [server]
 ACME_DIRECTORY=/data/gitea/https
 ```
 The rootless image keeps its working directory (`/var/lib/gitea`) in a volume,
 so it is only affected when that volume is not persisted.
 :::
 ## Using a reverse proxy
 Setup up your reverse proxy as shown in the [reverse proxy guide](../administration/reverse-proxies.md).
 After that, enable HTTPS by following one of these guides:
 - [nginx](https://nginx.org/en/docs/http/configuring_https_servers.html)
 - [apache2/httpd](https://httpd.apache.org/docs/2.4/ssl/ssl_howto.html)
 - [caddy](https://caddyserver.com/docs/tls)
 :::note
 Enabling HTTPS only at the proxy level is referred as [TLS Termination Proxy](https://en.wikipedia.org/wiki/TLS_termination_proxy). The proxy server accepts incoming TLS connections, decrypts the contents, and passes the now unencrypted contents to Gitea. This is normally fine as long as both the proxy and Gitea instances are either on the same machine, or on different machines within private network (with the proxy is exposed to outside network). If your Gitea instance is separated from your proxy over a public network, or if you want full end-to-end encryption, you can also [enable HTTPS support directly in Gitea using built-in server](#using-the-built-in-server) and forward the connections over HTTPS instead.
 :::
@@ -0,0 +1,284 @@
 ---
 date: "2019-04-02T17:06:00+01:00"
 slug: "logging-config"
 sidebar_position: 40
 aliases:
  - /en-us/logging-configuration
 ---
 # Logging Configuration
 The logging configuration of Gitea mainly consists of 3 types of components:
 - The `[log]` section for general configuration
 - `[log.<mode-name>]` sections for the configuration of different log writers to output logs, aka: "writer mode", the mode name is also used as "writer name".
 - The `[log]` section can also contain sub-logger configurations following the key schema `logger.<logger-name>.<CONFIG-KEY>`
 There is a fully functional log output by default, so it is not necessary to define one.
 ## Collecting Logs for Help
 To collect logs for help and issue report, see [Support Options](help/support.md).
 ## The `[log]` section
 Configuration of logging facilities in Gitea happen in the `[log]` section and its subsections.
 In the top level `[log]` section the following configurations can be placed:
 - `ROOT_PATH`: (Default: **%(GITEA_WORK_DIR)/log**): Base path for log files
 - `MODE`: (Default: **console**) List of log outputs to use for the Default logger.
 - `LEVEL`: (Default: **Info**) Least severe log events to persist, case-insensitive. Possible values are: `Trace`, `Debug`, `Info`, `Warn`, `Error`, `Fatal`.
 - `STACKTRACE_LEVEL`: (Default: **None**) For this and more severe events the stacktrace will be printed upon getting logged.
 And it can contain the following sub-loggers:
 - `logger.router.MODE`: (Default: **,**): List of log outputs to use for the Router logger.
 - `logger.access.MODE`: (Default: **_empty_**)  List of log outputs to use for the Access logger. By default, the access logger is disabled.
 - `logger.xorm.MODE`: (Default: **,**) List of log outputs to use for the XORM logger.
 Setting a comma (`,`) to sub-logger's mode means making it use the default global `MODE`.
 ## Quick samples
 ### Default (empty) Configuration
 The empty configuration is equivalent to default:
 ```ini
 [log]
 ROOT_PATH = %(GITEA_WORK_DIR)/log
 MODE = console
 LEVEL = Info
 STACKTRACE_LEVEL = None
 logger.router.MODE = ,
 logger.xorm.MODE = ,
 logger.access.MODE =
 ; this is the config options of "console" mode (used by MODE=console above)
 [log.console]
 MODE = console
 FLAGS = stdflags
 PREFIX =
 COLORIZE = true
 ```
 This is equivalent to sending all logs to the console, with default Golang log being sent to the console log too.
 This is only a sample, and it is the default, do not need to write it into your configuration file.
 ### Disable Router logs and record some access logs to file
 The Router logger is disabled, the access logs (>=Warn) goes into `access.log`:
 ```ini
 [log]
 logger.router.MODE =
 logger.access.MODE = access-file
 [log.access-file]
 MODE = file
 LEVEL = Warn
 FILE_NAME = access.log
 ```
 ### Set different log levels for different modes
 Default logs (>=Warn) goes into `gitea.log`, while Error logs goes into `file-error.log`:
 ```ini
 [log]
 LEVEL = Warn
 MODE = file, file-error
 ; by default, the "file" mode will record logs to %(log.ROOT_PATH)/gitea.log, so we don't need to set it
 ; [log.file]
 ; by default, the MODE (actually it's the output writer of this logger) is taken from the section name, so we don't need to set it either
 ; MODE = file
 [log.file-error]
 MODE = file
 LEVEL = Error
 FILE_NAME = file-error.log
 ```
 ## Log outputs (mode and writer)
 Gitea provides the following log output writers:
 - `console` - Log to `stdout` (or `stderr` if it is set in the config)
 - `file` - Log to a file
 - `conn` - Log to a socket (network or unix)
 ### Common configuration
 Certain configuration is common to all modes of log output:
 - `MODE` is the mode of the log output writer. It will default to the mode name in the ini section. Thus `[log.console]` will default to `MODE = console`.
 - `LEVEL` is the lowest level that this output will log.
 - `STACKTRACE_LEVEL` is the lowest level that this output will print a stacktrace.
 - `COLORIZE` will default to `true` for `console` as described, otherwise it will default to `false`.
 #### `EXPRESSION`
 `EXPRESSION` represents a regular expression that log events must match to be logged by the output writer.
 Either the log message, (with colors removed), must match or the `longfilename:linenumber:functionname` must match.
 NB: the whole message or string doesn't need to completely match.
 Please note this expression will be run in the writer's goroutine but not the logging event goroutine.
 #### `FLAGS`
 `FLAGS` represents the preceding logging context information that is
 printed before each message. It is a comma-separated string set. The order of values does not matter.
 It defaults to `stdflags` (= `date,time,medfile,shortfuncname,levelinitial`)
 Possible values are:
 - `none` or `,` - No flags.
 - `date` - the date in the local time zone: `2009/01/23`.
 - `time` - the time in the local time zone: `01:23:23`.
 - `microseconds` - microsecond resolution: `01:23:23.123123`. Assumes  time.
 - `longfile` - full file name and line number: `/a/b/c/d.go:23`.
 - `shortfile` - final file name element and line number: `d.go:23`.
 - `funcname` - function name of the caller: `runtime.Caller()`.
 - `shortfuncname` - last part of the function name. Overrides `funcname`.
 - `utc` - if date or time is set, use UTC rather than the local time zone.
 - `levelinitial` - initial character of the provided level in brackets eg. `[I]` for info.
 - `level` - level in brackets `[INFO]`.
 - `gopid` - the Goroutine-PID of the context.
 - `medfile` - last 20 characters of the filename - equivalent to `shortfile,longfile`.
 - `stdflags` - equivalent to `date,time,medfile,shortfuncname,levelinitial`.
 ### Console mode
 In this mode the logger will forward log messages to the stdout and
 stderr streams attached to the Gitea process.
 For loggers in console mode, `COLORIZE` will default to `true` if not
 on windows, or the Windows terminal can be set into ANSI mode or is a
 cygwin or Msys pipe.
 Settings:
 - `STDERR`: **false**: Whether the logger should print to `stderr` instead of `stdout`.
 ### File mode
 In this mode the logger will save log messages to a file.
 Settings:
 - `FILE_NAME`: The file to write the log events to, relative to `ROOT_PATH`, Default to `%(ROOT_PATH)/gitea.log`. Exception: access log will default to `%(ROOT_PATH)/access.log`.
 - `MAX_SIZE_SHIFT`: **28**: Maximum size shift of a single file. 28 represents 256Mb. For details see below.
 - `LOG_ROTATE` **true**: Whether to rotate the log files. TODO: if false, will it delete instead on daily rotate, or do nothing?.
 - `DAILY_ROTATE`: **true**: Whether to rotate logs daily.
 - `MAX_DAYS`: **7**: Delete rotated log files after this number of days.
 - `COMPRESS`: **true**: Whether to compress old log files by default with gzip.
 - `COMPRESSION_LEVEL`: **-1**: Compression level. For details see below.
 `MAX_SIZE_SHIFT` defines the maximum size of a file by left shifting 1 the given number of times (`1 << x`).
 The exact behavior at the time of v1.17.3 can be seen [here](https://github.com/go-gitea/gitea/blob/v1.17.3/modules/setting/log.go#L185).
 The useful values of `COMPRESSION_LEVEL` are from 1 (best speed) to 9 (best compression). [DefaultCompression](https://pkg.go.dev/compress/gzip#pkg-constants) (-1) and [HuffmanOnly](https://pkg.go.dev/compress/flate#HuffmanOnly) (-2) can also be chosen.
 Beware that better compression might come with higher resource usage.
 ### Conn mode
 In this mode the logger will send log messages over a network socket.
 Settings:
 - `ADDR`: **:7020**: Sets the address to connect to.
 - `PROTOCOL`: **tcp**: Set the protocol, either "tcp", "unix" or "udp".
 - `RECONNECT`: **false**: Try to reconnect when connection is lost.
 - `RECONNECT_ON_MSG`: **false**: Reconnect host for every single message.
 ### The "Router" logger
 The Router logger logs the following message types when Gitea's route handlers work:
 - `started` messages will be logged at TRACE level
 - `polling`/`completed` routers will be logged at INFO. Exception: "/assets" static resource requests are also logged at TRACE.
 - `slow` routers will be logged at WARN
 - `failed` routers will be logged at WARN
 ### The "XORM" logger
 To make XORM outputs SQL logs, the `LOG_SQL` in `[database]` section should also be set to `true`.
 ### The "Access" logger
 The Access logger is a new logger since Gitea 1.9. It provides a NCSA
 Common Log compliant log format. It's highly configurable but caution
 should be taken when changing its template. The main benefit of this
 logger is that Gitea can now log accesses in a standard log format so
 standard tools may be used.
 You can enable this logger using `logger.access.MODE = ...`.
 If desired the format of the Access logger can be changed by changing
 the value of the `ACCESS_LOG_TEMPLATE`.
 Please note, the access logger will log at `INFO` level, setting the
 `LEVEL` of this logger to `WARN` or above will result in no access logs.
 #### The ACCESS_LOG_TEMPLATE
 This value represents a go template. Its default value is
 ```tmpl
 {{.Ctx.RemoteHost}} - {{.Identity}} {{.Start.Format "[02/Jan/2006:15:04:05 -0700]" }} "{{.Ctx.Req.Method}} {{.Ctx.Req.URL.RequestURI}} {{.Ctx.Req.Proto}}" {{.ResponseWriter.Status}} {{.ResponseWriter.Size}} "{{.Ctx.Req.Referer}}" "{{.Ctx.Req.UserAgent}}"`
 ```
 The template is passed following options:
 - `Ctx` is the `context.Context`
 - `Identity` is the `SignedUserName` or `"-"` if the user is not logged in
 - `Start` is the start time of the request
 - `ResponseWriter` is the `http.ResponseWriter`
 Caution must be taken when changing this template as it runs outside of
 the standard panic recovery trap. The template should also be as simple
 as it runs for every request.
 ## Releasing-and-Reopening, Pausing and Resuming logging
 If you are running on Unix you may wish to release-and-reopen logs in order to use `logrotate` or other tools.
 It is possible force Gitea to release and reopen it's logging files and connections by sending `SIGUSR1` to the
 running process, or running `gitea manager logging release-and-reopen`.
 Alternatively, you may wish to pause and resume logging - this can be accomplished through the use of the
 `gitea manager logging pause` and `gitea manager logging resume` commands. Please note that whilst logging
 is paused log events below INFO level will not be stored and only a limited number of events will be stored.
 Logging may block, albeit temporarily, slowing Gitea considerably whilst paused - therefore it is
 recommended that pausing only done for a very short period of time.
 ## Adding and removing logging whilst Gitea is running
 It is possible to add and remove logging whilst Gitea is running using the `gitea manager logging add` and `remove` subcommands.
 This functionality can only adjust running log systems and cannot be used to start the access or router loggers if they
 were not already initialized. If you wish to start these systems you are advised to adjust the app.ini and (gracefully) restart
 the Gitea service.
 The main intention of these commands is to easily add a temporary logger to investigate problems on running systems where a restart
 may cause the issue to disappear.
 ## Using `logrotate` instead of built-in log rotation
 Gitea includes built-in log rotation, which should be enough for most deployments. However, if you instead want to use the `logrotate` utility:
 - Disable built-in log rotation by setting `LOG_ROTATE` to `false` in your `app.ini`.
 - Install `logrotate`.
 - Configure `logrotate` to match your deployment requirements, see `man 8 logrotate` for configuration syntax details.
  In the `postrotate/endscript` block send Gitea a `USR1` signal via `kill -USR1` or `kill -10` to the `gitea` process itself,
  or run `gitea manager logging release-and-reopen` (with the appropriate environment).
  Ensure that your configurations apply to all files emitted by Gitea loggers as described in the above sections.
 - Always do `logrotate /etc/logrotate.conf --debug` to test your configurations.
 - If you are using docker and are running from outside the container you can use
  `docker exec -u $OS_USER $CONTAINER_NAME sh -c 'gitea manager logging release-and-reopen'`
  or `docker exec $CONTAINER_NAME sh -c '/bin/s6-svc -1 /etc/s6/gitea/'` or send `USR1` directly to the Gitea process itself.
 The next `logrotate` jobs will include your configurations, so no restart is needed.
 You can also immediately reload `logrotate` with `logrotate /etc/logrotate.conf --force`.
@@ -0,0 +1,268 @@
 ---
 date: "2019-10-23T17:00:00-03:00"
 slug: "mail-templates"
 sidebar_position: 45
 aliases:
  - /en-us/mail-templates
 ---
 # Mail templates
 To craft the e-mail subject and contents for certain operations, Gitea can be customized by using templates. The templates
 for these functions are located under the [`custom` directory](../administration/customizing-gitea.md).
 Gitea has an internal template that serves as default in case there's no custom alternative.
 Custom templates are loaded when Gitea starts. Changes made to them are not recognized until Gitea is restarted again.
 ## Mail notifications supporting templates
 Currently, the following notification events make use of templates:
 | Action name | Usage                                                                                                        |
 | ----------- | ------------------------------------------------------------------------------------------------------------ |
 | `new`       | A new issue or pull request was created.                                                                     |
 | `comment`   | A new comment was created in an existing issue or pull request.                                              |
 | `close`     | An issue or pull request was closed.                                                                         |
 | `reopen`    | An issue or pull request was reopened.                                                                       |
 | `review`    | The head comment of a review in a pull request.                                                              |
 | `approve`   | The head comment of a approving review for a pull request.                                                   |
 | `reject`    | The head comment of a review requesting changes for a pull request.                                          |
 | `code`      | A single comment on the code of a pull request.                                                              |
 | `assigned`  | User was assigned to an issue or pull request.                                                               |
 | `default`   | Any action not included in the above categories, or when the corresponding category template is not present. |
 The path for the template of a particular message type is:
 ```sh
 custom/templates/mail/{action type}/{action name}.tmpl
 ```
 Where `{action type}` is one of `issue` or `pull` (for pull requests), and `{action name}` is one of the names listed above.
 For example, the specific template for a mail regarding a comment in a pull request is:
 ```sh
 custom/templates/mail/pull/comment.tmpl
 ```
 However, creating templates for each and every action type/name combination is not required.
 A fallback system is used to choose the appropriate template for an event. The _first existing_
 template on this list is used:
 - The specific template for the desired **action type** and **action name**.
 - The template for action type `issue` and the desired **action name**.
 - The template for the desired **action type**, action name `default`.
 - The template for action type `issue`, action name `default`.
 The only mandatory template is action type `issue`, action name `default`, which is already embedded in Gitea
 unless it's overridden by the user in the `custom` directory.
 ## Template syntax
 Mail templates are UTF-8 encoded text files that need to follow one of the following formats:
 ```
 Text and macros for the subject line
 ------------
 Text and macros for the mail body
 ```
 or
 ```
 Text and macros for the mail body
 ```
 Specifying a _subject_ section is optional (and therefore also the dash line separator). When used, the separator between
 _subject_ and _mail body_ templates requires at least three dashes; no other characters are allowed in the separator line.
 _Subject_ and _mail body_ are parsed by [Golang's template engine](https://go.dev/pkg/text/template/) and
 are provided with a _metadata context_ assembled for each notification. The context contains the following elements:
 | Name               | Type             | Available     | Usage                                                                                                                                                                                                                                             |
 | ------------------ | ---------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `.FallbackSubject` | string           | Always        | A default subject line. See Below.                                                                                                                                                                                                                |
 | `.Subject`         | string           | Only in body  | The _subject_, once resolved.                                                                                                                                                                                                                     |
 | `.Body`            | string           | Always        | The message of the issue, pull request or comment, parsed from Markdown into HTML and sanitized. Do not confuse with the _mail body_.                                                                                                             |
 | `.Link`            | string           | Always        | The address of the originating issue, pull request or comment.                                                                                                                                                                                    |
 | `.Issue`           | models.Issue     | Always        | The issue (or pull request) originating the notification. To get data specific to a pull request (e.g. `HasMerged`), `.Issue.PullRequest` can be used, but care should be taken as this field will be `nil` if the issue is _not_ a pull request. |
 | `.Comment`         | models.Comment   | If applicable | If the notification is from a comment added to an issue or pull request, this will contain the information about the comment.                                                                                                                     |
 | `.IsPull`          | bool             | Always        | `true` if the mail notification is associated with a pull request (i.e. `.Issue.PullRequest` is not `nil`).                                                                                                                                       |
 | `.Repo`            | string           | Always        | Name of the repository, including owner name (e.g. `mike/stuff`)                                                                                                                                                                                  |
 | `.User`            | models.User      | Always        | Owner of the repository from which the event originated. To get the user name (e.g. `mike`),`.User.Name` can be used.                                                                                                                             |
 | `.Doer`            | models.User      | Always        | User that executed the action triggering the notification event. To get the user name (e.g. `rhonda`), `.Doer.Name` can be used.                                                                                                                  |
 | `.IsMention`       | bool             | Always        | `true` if this notification was only generated because the user was mentioned in the comment, while not being subscribed to the source. It will be `false` if the recipient was subscribed to the issue or repository.                            |
 | `.SubjectPrefix`   | string           | Always        | `Re: ` if the notification is about other than issue or pull request creation; otherwise an empty string.                                                                                                                                         |
 | `.ActionType`      | string           | Always        | `"issue"` or `"pull"`. Will correspond to the actual _action type_ independently of which template was selected.                                                                                                                                  |
 | `.ActionName`      | string           | Always        | It will be one of the action types described above (`new`, `comment`, etc.), and will correspond to the actual _action name_ independently of which template was selected.                                                                        |
 | `.ReviewComments`  | []models.Comment | Always        | List of code comments in a review. The comment text will be in `.RenderedContent` and the referenced code will be in `.Patch`.                                                                                                                    |
 All names are case sensitive.
 ### The _subject_ part of the template
 The template engine used for the mail _subject_ is golang's [`text/template`](https://go.dev/pkg/text/template/).
 Please refer to the linked documentation for details about its syntax.
 The _subject_ is built using the following steps:
 - A template is selected according to the type of notification and to what templates are present.
 - The template is parsed and resolved (e.g. `{{.Issue.Index}}` is converted to the number of the issue
  or pull request).
 - All space-like characters (e.g. `TAB`, `LF`, etc.) are converted to normal spaces.
 - All leading, trailing and redundant spaces are removed.
 - The string is truncated to its first 256 runes (characters).
 If the end result is an empty string, **or** no subject template was available (i.e. the selected template
 did not include a subject part), Gitea's **internal default** will be used.
 The internal default (fallback) subject is the equivalent of:
 ```sh
 {{.SubjectPrefix}}[{{.Repo}}] {{.Issue.Title}} (#{{.Issue.Index}})
 ```
 For example: `Re: [mike/stuff] New color palette (#38)`
 Gitea's default subject can also be found in the template _metadata_ as `.FallbackSubject` from any of
 the two templates, even if a valid subject template is present.
 ### The _mail body_ part of the template
 The template engine used for the _mail body_ is golang's [`html/template`](https://go.dev/pkg/html/template/).
 Please refer to the linked documentation for details about its syntax.
 The _mail body_ is parsed after the mail subject, so there is an additional _metadata_ field which is
 the actual rendered subject, after all considerations.
 The expected result is HTML (including structural elements like`<html>`, `<body>`, etc.). Styling
 through `<style>` blocks, `class` and `style` attributes is possible. However, `html/template`
 does some [automatic escaping](https://go.dev/pkg/html/template/#hdr-Contexts) that should be considered.
 Attachments (such as images or external style sheets) are not supported. However, other templates can
 be referenced too, for example to provide the contents of a `<style>` element in a centralized fashion.
 The external template must be placed under `custom/mail` and referenced relative to that directory.
 For example, `custom/mail/styles/base.tmpl` can be included using `{{template styles/base}}`.
 The mail is sent with `Content-Type: multipart/alternative`, so the body is sent in both HTML
 and text formats. The latter is obtained by stripping the HTML markup.
 ## Troubleshooting
 How a mail is rendered is directly dependent on the capabilities of the mail application. Many mail
 clients don't even support HTML, so they show the text version included in the generated mail.
 If the template fails to render, it will be noticed only at the moment the mail is sent.
 A default subject is used if the subject template fails, and whatever was rendered successfully
 from the _mail body_ is used, disregarding the rest.
 Please check [Gitea's logs](../administration/logging-config.md) for error messages in case of trouble.
 ## Example
 `custom/templates/mail/issue/default.tmpl`:
 ```html
 [{{.Repo}}] @{{.Doer.Name}}
 {{if eq .ActionName "new"}}
    created
 {{else if eq .ActionName "comment"}}
    commented on
 {{else if eq .ActionName "close"}}
    closed
 {{else if eq .ActionName "reopen"}}
    reopened
 {{else}}
    updated
 {{end}}
 {{if eq .ActionType "issue"}}
    issue
 {{else}}
    pull request
 {{end}}
 #{{.Issue.Index}}: {{.Issue.Title}}
 ------------
 <!DOCTYPE html>
 <html>
 <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>{{.Subject}}</title>
 </head>
 <body>
    {{if .IsMention}}
    <p>
        You are receiving this because @{{.Doer.Name}} mentioned you.
    </p>
    {{end}}
    <p>
        <p>
        <a href="{{AppUrl}}/{{.Doer.LowerName}}">@{{.Doer.Name}}</a>
        {{if not (eq .Doer.FullName "")}}
            ({{.Doer.FullName}})
        {{end}}
        {{if eq .ActionName "new"}}
            created
        {{else if eq .ActionName "close"}}
            closed
        {{else if eq .ActionName "reopen"}}
            reopened
        {{else}}
            updated
        {{end}}
        <a href="{{.Link}}">{{.Repo}}#{{.Issue.Index}}</a>.
        </p>
        {{if not (eq .Body "")}}
            <h3>Message content</h3>
            <hr>
            {{.Body}}
        {{end}}
    </p>
    <hr>
    <p>
        <a href="{{.Link}}">View it on Gitea</a>.
    </p>
 </body>
 </html>
 ```
 This template produces something along these lines:
 ### Subject
 > [mike/stuff] @rhonda commented on pull request #38: New color palette
 ### Mail body
 > [@rhonda](#) (Rhonda Myers) updated [mike/stuff#38](#).
 >
 > #### Message content
 >
 > \_********************************\_********************************
 >
 > Mike, I think we should tone down the blues a little.
 > \_********************************\_********************************
 >
 > [View it on Gitea](#).
 ## Advanced
 The template system contains several functions that can be used to further process and format
 the messages. Here's a list of some of them:
 | Name             | Parameters  | Available | Usage                                                               |
 | ---------------- | ----------- | --------- | ------------------------------------------------------------------- |
 | `AppUrl`         | -           | Any       | Gitea's URL                                                         |
 | `AppName`        | -           | Any       | Set from `app.ini`, usually "Gitea"                                 |
 | `AppDomain`      | -           | Any       | Gitea's host name                                                   |
 | `EllipsisString` | string, int | Any       | Truncates a string to the specified length; adds ellipsis as needed |
 | `SanitizeHTML`   | string      | Body only | Sanitizes text by removing any dangerous HTML tags from it          |
 These are _functions_, not metadata, so they have to be used:
 ```html
 Like this:         {{SanitizeHTML "Escape<my>text"}}
 Or this:           {{"Escape<my>text" | SanitizeHTML}}
 Or this:           {{AppUrl}}
 But not like this: {{.AppUrl}}
 ```
@@ -1,18 +1,9 @@
 ---
 date: "2019-09-06T01:35:00-03:00"
 title: "Repository indexer"
 slug: "repo-indexer"
 sidebar_position: 45
 toc: false
 draft: false
 aliases:
  - /en-us/repo-indexer
 menu:
  sidebar:
    parent: "administration"
    name: "Repository indexer"
    sidebar_position: 45
    identifier: "repo-indexer"
 ---
 # Repository indexer
@@ -25,7 +16,7 @@ Better code search support could be achieved by setting up the repository indexe
 ## Setting up the repository indexer
-Gitea can search through the files of the repositories by enabling this function in your [`app.ini`](administration/config-cheat-sheet.md):
+Gitea can search through the files of the repositories by enabling this function in your [`app.ini`](../administration/config-cheat-sheet.md):
 ```ini
 [indexer]
@@ -41,7 +32,7 @@ Please bear in mind that indexing the contents can consume a lot of system resou
 ### Choosing the files for indexing by size
-The `MAX_FILE_SIZE` option will make the indexer skip all files larger than the specified value.
+The `MAX_FILE_SIZE` option will make the indexer skip all files larger than the specified value in bytes.
 ### Choosing the files for indexing by path
@@ -0,0 +1,461 @@
 ---
 date: "2018-05-22T11:00:00+00:00"
 slug: "reverse-proxies"
 sidebar_position: 16
 aliases:
  - /en-us/reverse-proxies
 ---
 # Reverse Proxies
 ## General configuration
 1. Set `[server] ROOT_URL = https://git.example.com/` in your `app.ini` file.
 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-Forwarded-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.
 6. Gitea uses a WebSocket connection at `/-/ws` for real-time updates like the notification counter. Make sure the reverse-proxy talks HTTP/1.1 and forwards the `Upgrade` and `Connection` headers, see the examples below. Without it, Gitea falls back to periodic polling.
 ### Use a sub-path
 Usually it's **not recommended** to put Gitea in a sub-path, it's not widely used and may have some issues in rare cases.
 To make Gitea work with a sub-path (eg: `https://common.example.com/gitea/`),
 there are some extra requirements besides the general configuration above:
 1. Use `[server] ROOT_URL = https://common.example.com/gitea/` in your `app.ini` file.
 2. Make the reverse-proxy pass `https://common.example.com/gitea/foo` to `http://gitea:3000/foo`.
 3. The container registry requires a fixed sub-path `/v2` at the root level which must be configured:
   - Make the reverse-proxy pass `https://common.example.com/v2` to `http://gitea:3000/v2`.
   - Make sure the URI and headers are also correctly passed (see the general configuration above).
 ## Nginx
 If you want Nginx to serve your Gitea instance, add the following `server` section to the `http` section of `nginx.conf`.
 Make sure `client_max_body_size` is large enough, otherwise there would be "413 Request Entity Too Large" error when uploading large files.
 ```nginx
 server {
    ...
    location / {
        client_max_body_size 512M;
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Connection $http_connection;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
 }
 ```
 ## Nginx with a sub-path
 In case you already have a site, and you want Gitea to share the domain name,
 you can setup Nginx to serve Gitea under a sub-path by adding the following `server` section
 into the `http` section of `nginx.conf`:
 ```nginx
 server {
    ...
    location ~ ^/(gitea|v2)($|/) {
        client_max_body_size 512M;
        # make nginx use unescaped URI, keep "%2F" as-is, remove the "/gitea" sub-path prefix, pass "/v2" as-is.
        rewrite ^ $request_uri;
        rewrite ^/(gitea($|/))?(.*) /$3 break;
        proxy_pass http://127.0.0.1:3000$uri;
        proxy_http_version 1.1;
        # other common HTTP headers, see the "Nginx" config section above
        proxy_set_header Connection $http_connection;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
 }
 ```
 Then you **MUST** set something like `[server] ROOT_URL = http://git.example.com/gitea/` correctly in your configuration.
 ## Nginx and serve static resources directly
 We can tune the performance in splitting requests into categories static and dynamic.
 CSS files, JavaScript files, images and web fonts are static content.
 The front page, a repository view or issue list is dynamic content.
 Nginx can serve static resources directly and proxy only the dynamic requests to Gitea.
 Nginx is optimized for serving static content, while the proxying of large responses might be the opposite of that
 (see [https://serverfault.com/q/587386](https://serverfault.com/q/587386)).
 Download a snapshot of the Gitea source repository to `/path/to/gitea/`.
 After this, run `make frontend` in the repository directory to generate the static resources. We are only interested in the `public/` directory for this task, so you can delete the rest.
 (You will need to have [Node with npm](https://nodejs.org/en/download/) and `make` installed to generate the static resources)
 Depending on the scale of your user base, you might want to split the traffic to two distinct servers,
 or use a cdn for the static files.
 ### Single node and single domain
 Set `[server] STATIC_URL_PREFIX = /_/static` in your configuration.
 ```nginx
 server {
    listen 80;
    server_name git.example.com;
    location /_/static/assets/ {
        alias /path/to/gitea/public/;
    }
    location / {
        # other directives, see the "Nginx" config section above
        proxy_pass http://localhost:3000;
    }
 }
 ```
 ### Two nodes and two domains
 Set `[server] STATIC_URL_PREFIX = http://cdn.example.com/gitea` in your configuration.
 ```nginx
 # application server running Gitea
 server {
    listen 80;
    server_name git.example.com;
    location / {
        # other directives, see the "Nginx" config section above
        proxy_pass http://localhost:3000;
    }
 }
 ```
 ```nginx
 # static content delivery server
 server {
    listen 80;
    server_name cdn.example.com;
    location /gitea/ {
        alias /path/to/gitea/public/;
    }
    location / {
        return 404;
    }
 }
 ```
 ## 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 line to it's configuration:
 ```nginx
 client_max_body_size 512M;
 ```
 Enable `Websockets Support` on the proxy host, Nginx Proxy Manager then adds the WebSocket directives itself. Adding `proxy_http_version` on top of that makes Nginx refuse to start.
 ## 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):
 ```apacheconf
 <VirtualHost *:80>
    ...
    ProxyPreserveHost On
    ProxyRequests off
    AllowEncodedSlashes NoDecode
    ProxyPass / http://localhost:3000/ nocanon upgrade=websocket
    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
 </VirtualHost>
 ```
 :::note
 The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`.
 `upgrade=websocket` requires Apache HTTPD 2.4.48 or later. On older versions you **MUST** remove it, otherwise Apache HTTPD will not start.
 :::
 If you wish to use Let's Encrypt with webroot validation, add the line `ProxyPass /.well-known !` before `ProxyPass` to disable proxying these requests to Gitea.
 ## Apache HTTPD with a sub-path
 In case you already have a site, and you want Gitea to share the domain name, you can setup Apache HTTPD to serve Gitea under a sub-path by adding the following to you Apache HTTPD configuration (usually located at `/etc/apache2/httpd.conf` in Ubuntu):
 ```apacheconf
 <VirtualHost *:80>
    ...
    <Proxy *>
         Order allow,deny
         Allow from all
    </Proxy>
    AllowEncodedSlashes NoDecode
    # Note: no trailing slash after either /git or port
    ProxyPass /git http://localhost:3000 nocanon upgrade=websocket
    ProxyPreserveHost On
    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
 </VirtualHost>
 ```
 Then you **MUST** set something like `[server] ROOT_URL = http://git.example.com/git/` correctly in your configuration.
 :::note
 The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`. `upgrade=websocket` requires Apache HTTPD 2.4.48 or later, remove it on older versions.
 :::
 ## Apache HTTPD and serve static resources directly
 We can tune the performance in splitting requests into categories static and dynamic.
 CSS files, JavaScript files, images and web fonts are static content.
 The front page, a repository view or issue list is dynamic content.
 Apache HTTPD can serve static resources directly and proxy only the dynamic requests to Gitea.
 Download a snapshot of the Gitea source repository to `/path/to/gitea/`.
 After this, run `make frontend` in the repository directory to generate the static resources. We are only interested in the `public/` directory for this task, so you can delete the rest.
 (You will need to have [Node with npm](https://nodejs.org/en/download/) and `make` installed to generate the static resources)
 Depending on the scale of your user base, you might want to split the traffic to two distinct servers,
 or use a cdn for the static files.
 ### Single node and single domain
 Set `[server] STATIC_URL_PREFIX = /_/static` in your configuration.
 ```apacheconf
 <VirtualHost *:80>
    ...
    <Proxy *>
         Order allow,deny
         Allow from all
    </Proxy>
    ProxyPass /_/static/ !
    Alias /_/static/ /path/to/gitea/public/
    <Directory /path/to/gitea/public/>
        Options FollowSymlinks
 		AllowOverride None
 		Require all granted
    </Directory>
    AllowEncodedSlashes NoDecode
    # Note: no trailing slash after either /git or port
    ProxyPass / http://localhost:3000/ nocanon upgrade=websocket
    ProxyPreserveHost On
    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
 </VirtualHost>
 ```
 :::note
 The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`. `upgrade=websocket` requires Apache HTTPD 2.4.48 or later, remove it on older versions.
 :::
 ## Caddy
 If you want Caddy to serve your Gitea instance, you can add the following server block to your Caddyfile:
 ```
 git.example.com {
    reverse_proxy localhost:3000
 }
 ```
 ## Caddy with a sub-path
 In case you already have a site, and you want Gitea to share the domain name, you can setup Caddy to serve Gitea under a sub-path by adding the following to your server block in your Caddyfile:
 ```
 git.example.com {
    route /git/* {
        uri strip_prefix /git
        reverse_proxy localhost:3000
    }
 }
 ```
 Then set `[server] ROOT_URL = http://git.example.com/git/` in your configuration.
 ## IIS
 If you wish to run Gitea with IIS. You will need to setup IIS with URL Rewrite as reverse proxy.
 1. Setup an empty website in IIS, named let's say, `Gitea Proxy`.
 2. Follow the first two steps in [Microsoft's Technical Community Guide to Setup IIS with URL Rewrite](https://techcommunity.microsoft.com/t5/iis-support-blog/setup-iis-with-url-rewrite-as-a-reverse-proxy-for-real-world/ba-p/846222#M343). That is:
 - Install Application Request Routing (ARR for short) either by using the Microsoft Web Platform Installer 5.1 (WebPI) or downloading the extension from [IIS.net](https://www.iis.net/downloads/microsoft/application-request-routing)
 - Once the module is installed in IIS, you will see a new Icon in the IIS Administration Console called URL Rewrite.
 - Install the `WebSocket Protocol` Windows feature, otherwise ARR cannot proxy Gitea's WebSocket endpoint.
 - Open the IIS Manager Console and click on the `Gitea Proxy` Website from the tree view on the left. Select and double click the URL Rewrite Icon from the middle pane to load the URL Rewrite interface.
 - Choose the `Add Rule` action from the right pane of the management console and select the `Reverse Proxy Rule` from the `Inbound and Outbound Rules` category.
 - In the Inbound Rules section, set the server name to be the host that Gitea is running on with its port. e.g. if you are running Gitea on the localhost with port 3000, the following should work: `127.0.0.1:3000`
 - Enable SSL Offloading
 - In the Outbound Rules, ensure `Rewrite the domain names of the links in HTTP response` is set and set the `From:` field as above and the `To:` to your external hostname, say: `git.example.com`
 - Turn `Reverse rewrite host in response headers` off, in the `Server Proxy Settings` of Application Request Routing (select the server node in the IIS Manager, open `Application Request Routing Cache`, then `Server Proxy Settings` in the right pane). While it is on, ARR rewrites the host of the `Location` header back to the internal one, so the redirects Gitea sends after a sign-in or a form submission send the browser to `127.0.0.1:3000` instead of `git.example.com`.
 - Now edit the `web.config` for your website to match the following: (changing `127.0.0.1:3000` and `git.example.com` as appropriate)
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <configuration>
    <system.web>
        <httpRuntime requestPathInvalidCharacters="" />
    </system.web>
    <system.webServer>
        <security>
          <requestFiltering>
            <hiddenSegments>
              <clear />
            </hiddenSegments>
            <denyUrlSequences>
              <clear />
            </denyUrlSequences>
            <fileExtensions allowUnlisted="true">
              <clear />
            </fileExtensions>
          </requestFiltering>
        </security>
        <rewrite>
            <rules useOriginalURLEncoding="false">
                <rule name="ReverseProxyInboundRule1" stopProcessing="true">
                    <match url="(.*)" />
                    <action type="Rewrite" url="http://127.0.0.1:3000{UNENCODED_URL}" />
                    <serverVariables>
                        <set name="HTTP_X_ORIGINAL_ACCEPT_ENCODING" value="HTTP_ACCEPT_ENCODING" />
                        <set name="HTTP_ACCEPT_ENCODING" value="" />
                    </serverVariables>
                </rule>
            </rules>
            <outboundRules>
                <rule name="ReverseProxyOutboundRule1" preCondition="ResponseIsHtml1">
                    <!-- set the pattern correctly here - if you only want to accept http or https -->
                    <!-- change the pattern and the action value as appropriate -->
                    <match filterByTags="A, Form, Img" pattern="^http(s)?://127.0.0.1:3000/(.*)" />
                    <action type="Rewrite" value="http{R:1}://git.example.com/{R:2}" />
                </rule>
                <rule name="RestoreAcceptEncoding" preCondition="NeedsRestoringAcceptEncoding">
                    <match serverVariable="HTTP_ACCEPT_ENCODING" pattern="^(.*)" />
                    <action type="Rewrite" value="{HTTP_X_ORIGINAL_ACCEPT_ENCODING}" />
                </rule>
                <preConditions>
                    <preCondition name="ResponseIsHtml1">
                        <add input="{RESPONSE_CONTENT_TYPE}" pattern="^text/html" />
                    </preCondition>
                    <preCondition name="NeedsRestoringAcceptEncoding">
                        <add input="{HTTP_X_ORIGINAL_ACCEPT_ENCODING}" pattern=".+" />
                    </preCondition>
                </preConditions>
            </outboundRules>
        </rewrite>
        <urlCompression doDynamicCompression="true" />
        <handlers>
          <clear />
          <add name="StaticFile" path="*" verb="*" modules="StaticFileModule,DefaultDocumentModule,DirectoryListingModule" resourceType="Either" requireAccess="Read" />
        </handlers>
        <!-- Map all extensions to the same MIME type, so all files can be
               downloaded. -->
        <staticContent>
          <clear />
          <mimeMap fileExtension="*" mimeType="application/octet-stream" />
        </staticContent>
    </system.webServer>
 </configuration>
 ```
 ## HAProxy
 If you want HAProxy to serve your Gitea instance, you can add the following to your HAProxy configuration
 add an acl in the frontend section to redirect calls to gitea.example.com to the correct backend
 ```
 frontend http-in
    ...
    acl acl_gitea hdr(host) -i gitea.example.com
    use_backend gitea if acl_gitea
    ...
 ```
 add the previously defined backend section
 ```
 backend gitea
    server localhost:3000 check
 ```
 If you redirect the http content to https, the configuration work the same way, just remember that the connection between HAProxy and Gitea will be done via http so you do not have to enable https in Gitea's configuration.
 ## HAProxy with a sub-path
 In case you already have a site, and you want Gitea to share the domain name, you can setup HAProxy to serve Gitea under a sub-path by adding the following to you HAProxy configuration:
 ```
 frontend http-in
    ...
    acl acl_gitea path_beg /gitea
    use_backend gitea if acl_gitea
    ...
 ```
 With that configuration http://example.com/gitea/ will redirect to your Gitea instance.
 then for the backend section
 ```
 backend gitea
    http-request replace-path /gitea\/?(.*) \/\1
    server localhost:3000 check
 ```
 The added http-request will automatically add a trailing slash if needed and internally remove /gitea from the path to allow it to work correctly with Gitea by setting properly http://example.com/gitea as the root.
 Then you **MUST** set something like `[server] ROOT_URL = http://example.com/gitea/` correctly in your configuration.
 ## Traefik
 If you want traefik to serve your Gitea instance, you can add the following label section to your `docker-compose.yaml` (Assuming the provider is docker).
 ```yaml
 gitea:
  image: docker.io/gitea/gitea
  ...
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.gitea.rule=Host(`example.com`)"
    - "traefik.http.services.gitea-websecure.loadbalancer.server.port=3000"
 ```
 This config assumes that you are handling HTTPS on the traefik side and using HTTP between Gitea and traefik.
 ## Traefik with a sub-path
 In case you already have a site, and you want Gitea to share the domain name, you can setup Traefik to serve Gitea under a sub-path by adding the following to your `docker-compose.yaml` (Assuming the provider is docker) :
 ```yaml
 gitea:
  image: docker.io/gitea/gitea
  ...
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.gitea.rule=Host(`example.com`) && PathPrefix(`/gitea`)"
    - "traefik.http.services.gitea-websecure.loadbalancer.server.port=3000"
    - "traefik.http.middlewares.gitea-stripprefix.stripprefix.prefixes=/gitea"
    - "traefik.http.routers.gitea.middlewares=gitea-stripprefix"
 ```
 This config assumes that you are handling HTTPS on the traefik side and using HTTP between Gitea and traefik.
 Then you **MUST** set something like `[server] ROOT_URL = http://example.com/gitea/` correctly in your configuration.
@@ -1,21 +1,12 @@
 ---
 date: "2019-12-31T13:55:00+05:00"
 title: "Search Engines Indexation"
 slug: "search-engines-indexation"
 sidebar_position: 60
 toc: false
 draft: false
 aliases:
  - /en-us/search-engines-indexation
 menu:
  sidebar:
    parent: "administration"
    name: "Search Engines Indexation"
    sidebar_position: 60
    identifier: "search-engines-indexation"
 ---
-# Search engines indexation of your Gitea installation
+# Search Engines Indexation
 By default your Gitea installation will be indexed by search engines.
 If you don't want your repository to be visible for search engines read further.
@@ -23,7 +14,7 @@ If you don't want your repository to be visible for search engines read further.
 ## Block search engines indexation using robots.txt
 To make Gitea serve a custom `robots.txt` (default: empty 404) for top level installations,
-create a file with path `public/robots.txt` in the [`custom` folder or `CustomPath`](administration/customizing-gitea.md)
+create a file with path `public/robots.txt` in the [`custom` folder or `CustomPath`](../administration/customizing-gitea.md)
 Examples on how to configure the `robots.txt` can be found at [https://moz.com/learn/seo/robotstxt](https://moz.com/learn/seo/robotstxt).
@@ -0,0 +1,212 @@
 ---
 date: "2019-08-17T10:20:00+01:00"
 slug: "signing"
 sidebar_position: 50
 aliases:
  - /en-us/signing
 ---
 # GPG/SSH Commit Signatures
 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.
 A commit will be marked with a grey unlocked icon if no key can be
 found to verify it. If a commit is marked with a red unlocked icon,
 it is reported to be signed with a key with an id.
 :::note
 The signer of a commit does not have to be an author or
 committer of a commit.
 :::
 ## Automatic Signing
 There are a number of places where Gitea will generate commits itself:
 - Repository Initialisation
 - Wiki Changes
 - CRUD actions using the editor or the API
 - Merges from Pull Requests
 Depending on configuration and server trust you may want Gitea to
 sign these commits.
 ## Installing and generating a GPG key for Gitea
 It is up to a server administrator to determine how best to install
 a signing key. Gitea generates all its commits using the server `git`
 command at present - and therefore the server `gpg` will be used for
 signing (if configured.) Administrators should review best-practices
 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
 `[repository.signing]` section of `app.ini`:
 ```ini
 ...
 [repository.signing]
 SIGNING_KEY = default
 SIGNING_NAME =
 SIGNING_EMAIL =
 INITIAL_COMMIT = always
 CRUD_ACTIONS = pubkey, twofa, parentsigned
 WIKI = never
 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 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
 of the `user.signingkey`, `user.name` and `user.email` as appropriate.
 By adjusting Git's `config` file within Gitea's
 repositories, `SIGNING_KEY=default` could be used to provide different
 signing keys on a per-repository basis. However, this is clearly not an
 ideal UI and therefore subject to change.
 :::warning
 **Since 1.17**, Gitea runs git in its own home directory `[git].HOME_PATH` (default to `%(APP_DATA_PATH)/home`)
 and uses its own config `{[git].HOME_PATH}/.gitconfig`.
 If you have your own customized git config for Gitea, you should set these configs in system git config (aka `/etc/gitconfig`)
 or the Gitea internal git config `{[git].HOME_PATH}/.gitconfig`.
 Related home files for git command (like `.gnupg`) should also be put in Gitea's git home directory `[git].HOME_PATH`.
 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
 when creating a repository. The possible values are:
 - `never`: Never sign
 - `pubkey`: Only sign if the user has a public key
 - `twofa`: Only sign if the user logs in with two factor authentication
 - `always`: Always sign
 Options other than `never` and `always` can be combined as a comma
 separated list. The commit will be signed if all selected options are true.
 ### `WIKI`
 This options determines if Gitea should sign commits to the Wiki.
 The possible values are:
 - `never`: Never sign
 - `pubkey`: Only sign if the user has a public key
 - `twofa`: Only sign if the user logs in with two-factor authentication
 - `parentsigned`: Only sign if the parent commit is signed.
 - `always`: Always sign
 Options other than `never` and `always` can be combined as a comma
 separated list. The commit will be signed if all selected options are true.
 ### `CRUD_ACTIONS`
 This option determines if Gitea should sign commits from the web
 editor or API CRUD actions. The possible values are:
 - `never`: Never sign
 - `pubkey`: Only sign if the user has a public key
 - `twofa`: Only sign if the user logs in with two-factor authentication
 - `parentsigned`: Only sign if the parent commit is signed.
 - `always`: Always sign
 Options other than `never` and `always` can be combined as a comma
 separated list. The change will be signed if all selected options are true.
 ### `MERGES`
 This option determines if Gitea should sign merge commits from PRs.
 The possible options are:
 - `never`: Never sign
 - `pubkey`: Only sign if the user has a public key
 - `twofa`: Only sign if the user logs in with two-factor authentication
 - `basesigned`: Only sign if the parent commit in the base repo is signed.
 - `headsigned`: Only sign if the head commit in the head branch is signed.
 - `commitssigned`: Only sign if all the commits in the head branch to the merge point are signed.
 - `approved`: Only sign approved merges to a protected branch.
 - `always`: Always sign
 Options other than `never` and `always` can be combined as a comma
 separated list. The merge will be signed if all selected options are true.
 ## Obtaining the Public Key of the Signing Key
 The public key used to sign Gitea's commits can be obtained from the API at:
 ```sh
 /api/v1/signing-key.gpg
 ```
 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
 ```