mirror of
https://github.com/go-gitea/gitea
synced 2024-11-25 02:42:49 +01:00
Added Table of Contents to long documentation pages (#13890)
* Redo #13836 with new shortcode (https://gitea.com/gitea/theme/pulls/90) * add Api Usage Co-authored-by: techknowlogick <techknowlogick@gitea.io>
This commit is contained in:
6543
GitHub
parent
e7938c9c44
commit
6bdcacd73b
20 changed files with 82 additions and 66 deletions
|
|
@ -31,6 +31,8 @@ Values containing `#` or `;` must be quoted using `` ` `` or `"""`.
|
|||
|
||||
**Note:** A full restart is required for Gitea configuration changes to take effect.
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
## Overall (`DEFAULT`)
|
||||
|
||||
- `APP_NAME`: **Gitea: Git with a cup of tea**: Application name, used in the page title.
|
||||
|
|
|
|||
|
|
@ -17,6 +17,8 @@ menu:
|
|||
|
||||
这是针对Gitea配置文件的说明，你可以了解Gitea的强大配置。需要说明的是，你的所有改变请修改 `custom/conf/app.ini` 文件而不是源文件。所有默认值可以通过 [app.example.ini](https://github.com/go-gitea/gitea/blob/master/custom/conf/app.example.ini) 查看到。如果你发现 `%(X)s` 这样的内容，请查看 [ini](https://github.com/go-ini/ini/#recursive-values) 这里的说明。标注了 :exclamation: 的配置项表明除非你真的理解这个配置项的意义，否则最好使用默认值。
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
## Overall (`DEFAULT`)
|
||||
|
||||
- `APP_NAME`: 应用名称，改成你希望的名字。
|
||||
|
|
|
|||
|
|
@ -45,6 +45,10 @@ environment variable; this can be used to override the default path to something
|
|||
|
||||
**Note:** Gitea must perform a full restart to see configuration changes.
|
||||
|
||||
# Table of Contents
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
## Serving custom public files
|
||||
|
||||
To make Gitea serve custom public files (like pages and images), use the folder
|
||||
|
|
|
|||
|
|
@ -17,6 +17,8 @@ menu:
|
|||
|
||||
The logging framework has been revamped in Gitea 1.9.0.
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
## Log Groups
|
||||
|
||||
The fundamental thing to be aware of in Gitea is that there are several
|
||||
|
|
|
|||
|
|
@ -21,6 +21,8 @@ Gitea has an internal template that serves as default in case there's no custom
|
|||
|
||||
Custom templates are loaded when Gitea starts. Changes made to them are not recognized until Gitea is restarted again.
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
## Mail notifications supporting templates
|
||||
|
||||
Currently, the following notification events make use of templates:
|
||||
|
|
@ -235,11 +237,11 @@ Please check [Gitea's logs](https://docs.gitea.io/en-us/logging-configuration/)
|
|||
|
||||
This template produces something along these lines:
|
||||
|
||||
#### Subject
|
||||
### Subject
|
||||
|
||||
> [mike/stuff] @rhonda commented on pull request #38: New color palette
|
||||
|
||||
#### Mail body
|
||||
### Mail body
|
||||
|
||||
> [@rhonda](#) (Rhonda Myers) updated [mike/stuff#38](#).
|
||||
>
|
||||
|
|
|
|||
|
|
@ -13,7 +13,9 @@ menu:
|
|||
identifier: "api-usage"
|
||||
---
|
||||
|
||||
# Gitea API Usage
|
||||
# API Usage
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
## Enabling/configuring API access
|
||||
|
||||
|
|
@ -22,7 +24,7 @@ By default, `ENABLE_SWAGGER` is true, and
|
|||
Sheet](https://docs.gitea.io/en-us/config-cheat-sheet/) for more
|
||||
information.
|
||||
|
||||
## Authentication via the API
|
||||
## Authentication
|
||||
|
||||
Gitea supports these methods of API authentication:
|
||||
|
||||
|
|
@ -39,7 +41,7 @@ Gitea parses queries and headers to find the token in
|
|||
You can create an API key token via your Gitea installation's web interface:
|
||||
`Settings | Applications | Generate New Token`.
|
||||
|
||||
### OAuth2
|
||||
## OAuth2 Provider
|
||||
|
||||
Access tokens obtained from Gitea's [OAuth2 provider](https://docs.gitea.io/en-us/oauth2-provider) are accepted by these methods:
|
||||
|
||||
|
|
|
|||
|
|
@ -15,6 +15,8 @@ menu:
|
|||
|
||||
# Hacking on Gitea
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
## Installing go
|
||||
|
||||
You should [install go](https://golang.org/doc/install) and set up your go
|
||||
|
|
@ -42,7 +44,7 @@ running. As of last update, it should be Go version {{< go-version >}}.
|
|||
Gitea makes heavy use of Make to automate tasks and improve development. This
|
||||
guide covers how to install Make.
|
||||
|
||||
#### On Linux
|
||||
### On Linux
|
||||
|
||||
Install with the package manager.
|
||||
|
||||
|
|
@ -58,7 +60,7 @@ On Fedora/RHEL/CentOS:
|
|||
sudo yum install make
|
||||
```
|
||||
|
||||
#### On Windows
|
||||
### On Windows
|
||||
|
||||
One of these three distributions of Make will run on Windows:
|
||||
|
||||
|
|
|
|||
|
|
@ -15,6 +15,8 @@ menu:
|
|||
|
||||
# Authentication
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
## LDAP (Lightweight Directory Access Protocol)
|
||||
|
||||
Both the LDAP via BindDN and the simple auth LDAP share the following fields:
|
||||
|
|
|
|||
|
|
@ -18,37 +18,7 @@ menu:
|
|||
This page contains some common questions and answers.
|
||||
Also see [Support Options]({{< relref "doc/help/seek-help.en-us.md" >}})
|
||||
|
||||
- [Difference between 1.x and 1.x.x downloads](#difference-between-1x-and-1xx-downloads)
|
||||
- [How to migrate from Gogs/GitHub/etc. to Gitea](#how-to-migrate-from-gogsgithubetc-to-gitea)
|
||||
- [Where does Gitea store what file](#where-does-gitea-store-what-file)
|
||||
- [Not seeing a clone URL or the clone URL being incorrect](#not-seeing-a-clone-url-or-the-clone-url-being-incorrect)
|
||||
- [Custom Templates not loading or working incorrectly](#custom-templates-not-loading-or-working-incorrectly)
|
||||
- [Active user vs login prohibited user](#active-user-vs-login-prohibited-user)
|
||||
- [Setting up logging](#setting-up-logging)
|
||||
- [What is Swagger?](#what-is-swagger)
|
||||
- [Adjusting your server for public/private use](#adjusting-your-server-for-publicprivate-use)
|
||||
- [Preventing spammers](#preventing-spammers)
|
||||
- [Only allow certain email domains](#only-allow-certain-email-domains)
|
||||
- [Only allow/block certain OpenID providers](#only-allowblock-certain-openid-providers)
|
||||
- [Issue only users](#issue-only-users)
|
||||
- [Restricted users](#restricted-users)
|
||||
- [Enable Fail2ban](#enable-fail2ban)
|
||||
- [How to add/use custom themes](#how-to-adduse-custom-themes)
|
||||
- [SSHD vs built-in SSH](#sshd-vs-built-in-ssh)
|
||||
- [Gitea is running slow](#gitea-is-running-slow)
|
||||
- [Can't create repositories/files](#cant-create-repositoriesfiles)
|
||||
- [Translation is incorrect/how to add more translations](#translation-is-incorrecthow-to-add-more-translations)
|
||||
- [Hooks aren't running](#hooks-arent-running)
|
||||
- [SSH issues](#ssh-issues)
|
||||
- [SSH Common Errors](#ssh-common-errors)
|
||||
- [Missing releases after migrating repository with tags](#missing-releases-after-migrating-repository-with-tags)
|
||||
- [LFS Issues](#lfs-issues)
|
||||
- [How can I create users before starting Gitea](#how-can-i-create-users-before-starting-gitea)
|
||||
- [How can I enable password reset](#how-can-i-enable-password-reset)
|
||||
- [How can a user's password be changed](#how-can-a-users-password-be-changed)
|
||||
- [Why is my markdown broken](#why-is-my-markdown-broken)
|
||||
- [Upgrade errors with MySQL](#upgrade-errors-with-mysql)
|
||||
- [Why Are Emoji Broken On MySQL](#why-are-emoji-broken-on-mysql)
|
||||
{{< toc >}}
|
||||
|
||||
## Difference between 1.x and 1.x.x downloads
|
||||
Version 1.7.x will be used for this example.
|
||||
|
|
|
|||
|
|
@ -13,12 +13,16 @@ menu:
|
|||
identifier: "database-prep"
|
||||
---
|
||||
|
||||
# Database Preparation
|
||||
|
||||
You need a database to use Gitea. Gitea supports PostgreSQL, MySQL, SQLite, and MSSQL. This page will guide into preparing database. Only PostgreSQL and MySQL will be covered here since those database engines are widely-used in production.
|
||||
|
||||
Database instance can be on same machine as Gitea (local database setup), or on different machine (remote database).
|
||||
|
||||
Note: All steps below requires that the database engine of your choice is installed on your system. For remote database setup, install the server part on database instance and client part on your Gitea server. In addition, make sure you use same engine version for both server and client for some engine features to work. For security reason, protect `root` (MySQL) or `postgres` (PostgreSQL) database superuser with secure password. The steps assumes that you run Linux for both database and Gitea servers.
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
## MySQL
|
||||
|
||||
1. For remote database setup, you will need to make MySQL listen to your IP address. Edit `bind-address` option on `/etc/mysql/my.cnf` on database instance to:
|
||||
|
|
|
|||
|
|
@ -16,9 +16,13 @@ menu:
|
|||
# Installation from binary
|
||||
|
||||
All downloads come with SQLite, MySQL and PostgreSQL support, and are built with
|
||||
embedded assets. This can be different for older releases. Choose the file matching
|
||||
the destination platform from the [downloads page](https://dl.gitea.io/gitea/), copy
|
||||
the URL and replace the URL within the commands below:
|
||||
embedded assets. This can be different for older releases.
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
## Download
|
||||
|
||||
Choose the file matching the destination platform from the [downloads page](https://dl.gitea.io/gitea/), copy the URL and replace the URL within the commands below:
|
||||
|
||||
```sh
|
||||
wget -O gitea https://dl.gitea.io/gitea/{{< version >}}/gitea-{{< version >}}-linux-amd64
|
||||
|
|
|
|||
|
|
@ -15,6 +15,8 @@ menu:
|
|||
|
||||
# Installation from package
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
## Alpine Linux
|
||||
|
||||
Alpine Linux has [Gitea](https://pkgs.alpinelinux.org/packages?name=gitea&branch=edge) in its community repository which follows the latest stable version.
|
||||
|
|
|
|||
|
|
@ -36,6 +36,8 @@ obtain the same version as our continuous integration, see the advice given in
|
|||
<a href='{{< relref "doc/developers/hacking-on-gitea.en-us.md" >}}'>Hacking on
|
||||
Gitea</a>
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
## Download
|
||||
|
||||
First, we must retrieve the source code. Since, the advent of go modules, the
|
||||
|
|
|
|||
|
|
@ -23,6 +23,8 @@ This reference setup guides users through the setup based on `docker-compose`, b
|
|||
of `docker-compose` is out of scope of this documentation. To install `docker-compose` itself, follow
|
||||
the official [install instructions](https://docs.docker.com/compose/install/).
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
## Basics
|
||||
|
||||
The most simple setup just creates a volume and a network and starts the `gitea/gitea:latest`
|
||||
|
|
|
|||
|
|
@ -17,6 +17,8 @@ menu:
|
|||
|
||||
Nous fournissons des images Docker mises à jour automatiquement via le Docker Hub de notre organisation. C'est à vous, lors devotre déploiement, de vous assurez d'utiliser toujours la dernière version stable ou d'utiliser un autre service qui met à jour l'image Docker pour vous.
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
## Données stockées sur l'hôte
|
||||
|
||||
Tout d'abord, vous devez simplement récupérer l'image Docker avec la commande suivante :
|
||||
|
|
|
|||
|
|
@ -17,6 +17,8 @@ menu:
|
|||
|
||||
阅读本章之前我们已经假设您对docker已经有了解并能够正常使用docker。
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
我们在 Docker Hub 的 Gitea 组织中提供了自动更新的 Docker 镜像，它会保持最新的稳定版。你也可以用其它 Docker 服务来更新。首先你需要pull镜像：
|
||||
|
||||
```
|
||||
|
|
|
|||
|
|
@ -15,6 +15,8 @@ menu:
|
|||
|
||||
# 用 Docker 安裝
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
我們在 Docker Hub 提供了自動更新的映像檔，它會保持最新穩定版。根據您的部屬環境來使用最新版本或用其他服務來更新 Docker 映像檔。首先您需要下載映像檔：
|
||||
|
||||
```
|
||||
|
|
|
|||
|
|
@ -13,13 +13,15 @@ menu:
|
|||
identifier: "command-line"
|
||||
---
|
||||
|
||||
## Command Line
|
||||
# Command Line
|
||||
|
||||
### Usage
|
||||
{{< toc >}}
|
||||
|
||||
## Usage
|
||||
|
||||
`gitea [global options] command [command or global options] [arguments...]`
|
||||
|
||||
### Global options
|
||||
## Global options
|
||||
|
||||
All global options can be placed at the command level.
|
||||
|
||||
|
|
@ -32,9 +34,9 @@ All global options can be placed at the command level.
|
|||
NB: The defaults custom-path, config and work-path can also be
|
||||
changed at build time (if preferred).
|
||||
|
||||
### Commands
|
||||
## Commands
|
||||
|
||||
#### web
|
||||
### web
|
||||
|
||||
Starts the server:
|
||||
|
||||
|
|
@ -51,7 +53,7 @@ Starts the server:
|
|||
Linux: `sudo setcap 'cap_net_bind_service=+ep' /path/to/gitea`. This will need to be
|
||||
redone every time you update Gitea.
|
||||
|
||||
#### admin
|
||||
### admin
|
||||
|
||||
Admin operations:
|
||||
|
||||
|
|
@ -229,7 +231,7 @@ Admin operations:
|
|||
- `gitea admin auth update-ldap-simple --id 1 --name "my ldap auth source"`
|
||||
- `gitea admin auth update-ldap-simple --id 1 --username-attribute uid --firstname-attribute givenName --surname-attribute sn`
|
||||
|
||||
#### cert
|
||||
### cert
|
||||
|
||||
Generates a self-signed SSL certificate. Outputs to `cert.pem` and `key.pem` in the current
|
||||
directory and will overwrite any existing files.
|
||||
|
|
@ -247,7 +249,7 @@ directory and will overwrite any existing files.
|
|||
- Examples:
|
||||
- `gitea cert --host git.example.com,example.com,www.example.com --ca`
|
||||
|
||||
#### dump
|
||||
### dump
|
||||
|
||||
Dumps all files and databases into a zip file. Outputs into a file like `gitea-dump-1482906742.zip`
|
||||
in the current directory.
|
||||
|
|
@ -262,7 +264,7 @@ in the current directory.
|
|||
- `gitea dump`
|
||||
- `gitea dump --verbose`
|
||||
|
||||
#### generate
|
||||
### generate
|
||||
|
||||
Generates random values and tokens for usage in configuration file. Useful for generating values
|
||||
for automatic deployments.
|
||||
|
|
@ -278,7 +280,7 @@ for automatic deployments.
|
|||
- `gitea generate secret JWT_SECRET`
|
||||
- `gitea generate secret SECRET_KEY`
|
||||
|
||||
#### keys
|
||||
### keys
|
||||
|
||||
Provides an SSHD AuthorizedKeysCommand. Needs to be configured in the sshd config file:
|
||||
|
||||
|
|
@ -300,14 +302,14 @@ writable by group or others. The program must be specified by an absolute
|
|||
path.
|
||||
NB: Gitea must be running for this command to succeed.
|
||||
|
||||
#### migrate
|
||||
### migrate
|
||||
Migrates the database. This command can be used to run other commands before starting the server for the first time.
|
||||
This command is idempotent.
|
||||
|
||||
#### convert
|
||||
### convert
|
||||
Converts an existing MySQL database from utf8 to utf8mb4.
|
||||
|
||||
#### doctor
|
||||
### doctor
|
||||
Diagnose the problems of current gitea instance according the given configuration.
|
||||
Currently there are a check list below:
|
||||
|
||||
|
|
@ -332,7 +334,7 @@ var checklist = []check{
|
|||
|
||||
This function will receive a command line context and return a list of details about the problems or error.
|
||||
|
||||
##### doctor recreate-table
|
||||
#### doctor recreate-table
|
||||
|
||||
Sometimes when there are migrations the old columns and default values may be left
|
||||
unchanged in the database schema. This may lead to warning such as:
|
||||
|
|
@ -362,7 +364,7 @@ gitea doctor recreate-table
|
|||
|
||||
It is highly recommended to back-up your database before running these commands.
|
||||
|
||||
#### manager
|
||||
### manager
|
||||
|
||||
Manage running server operations:
|
||||
|
||||
|
|
|
|||
|
|
@ -27,6 +27,8 @@ for them to be recognized. For example, they should not be included inside code
|
|||
text. They should also be reasonably cleared from their surrounding text
|
||||
(for example, using spaces).
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
## User, Team and Organization Mentions
|
||||
|
||||
When a text in the form `@username` is found and `username` matches the name
|
||||
|
|
|
|||
|
|
@ -13,7 +13,11 @@ menu:
|
|||
identifier: "reverse-proxies"
|
||||
---
|
||||
|
||||
## Using Nginx as a reverse proxy
|
||||
# Reverse Proxies
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
## Nginx
|
||||
If you want Nginx to serve your Gitea instance, add the following `server` section to the `http` section of `nginx.conf`:
|
||||
|
||||
```
|
||||
|
|
@ -27,7 +31,7 @@ server {
|
|||
}
|
||||
```
|
||||
|
||||
## Using Nginx with a sub-path as a reverse proxy
|
||||
## 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 inside the `http` section of `nginx.conf`:
|
||||
|
||||
|
|
@ -44,7 +48,7 @@ server {
|
|||
|
||||
Then set `[server] ROOT_URL = http://git.example.com/git/` in your configuration.
|
||||
|
||||
## Using Nginx as a reverse proxy and serve static resources directly
|
||||
## 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.
|
||||
|
|
@ -61,7 +65,7 @@ After this, run `make frontend` in the repository directory to generate the stat
|
|||
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.
|
||||
|
||||
### using a single node and a single domain
|
||||
### Single node and single domain
|
||||
|
||||
Set `[server] STATIC_URL_PREFIX = /_/static` in your configuration.
|
||||
|
||||
|
|
@ -80,7 +84,7 @@ server {
|
|||
}
|
||||
```
|
||||
|
||||
### using two nodes and two domains
|
||||
### Two nodes and two domains
|
||||
|
||||
Set `[server] STATIC_URL_PREFIX = http://cdn.example.com/gitea` in your configuration.
|
||||
|
||||
|
|
@ -112,7 +116,7 @@ server {
|
|||
}
|
||||
```
|
||||
|
||||
## Using Apache HTTPD as a reverse proxy
|
||||
## 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):
|
||||
|
||||
|
|
@ -131,7 +135,7 @@ Note: The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`
|
|||
|
||||
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.
|
||||
|
||||
## Using Apache HTTPD with a sub-path as a reverse proxy
|
||||
## 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):
|
||||
|
||||
|
|
@ -153,7 +157,7 @@ Then set `[server] ROOT_URL = http://git.example.com/git/` in your configuration
|
|||
|
||||
Note: The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`
|
||||
|
||||
## Using Caddy as a reverse proxy
|
||||
## Caddy
|
||||
|
||||
If you want Caddy to serve your Gitea instance, you can add the following server block to your Caddyfile:
|
||||
|
||||
|
|
@ -171,7 +175,7 @@ git.example.com {
|
|||
}
|
||||
```
|
||||
|
||||
## Using Caddy with a sub-path as a reverse proxy
|
||||
## 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:
|
||||
|
||||
|
|
@ -194,7 +198,7 @@ git.example.com {
|
|||
|
||||
Then set `[server] ROOT_URL = http://git.example.com/git/` in your configuration.
|
||||
|
||||
## Using IIS as a reverse proxy
|
||||
## IIS
|
||||
|
||||
If you wish to run Gitea with IIS. You will need to setup IIS with URL Rewrite as reverse proxy.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue