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 2020-12-08 04:52:26 +00:00 committed by GitHub
parent e7938c9c44
commit 6bdcacd73b
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
20 changed files with 82 additions and 66 deletions

View file

@ -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.

View file

@ -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`: 应用名称,改成你希望的名字。

View file

@ -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

View file

@ -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

View file

@ -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](#).
>

View file

@ -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:

View file

@ -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:

View file

@ -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:

View file

@ -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.

View file

@ -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:

View file

@ -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

View file

@ -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.

View file

@ -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

View file

@ -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`

View file

@ -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 :

View file

@ -17,6 +17,8 @@ menu:
阅读本章之前我们已经假设您对docker已经有了解并能够正常使用docker。
{{< toc >}}
我们在 Docker Hub 的 Gitea 组织中提供了自动更新的 Docker 镜像,它会保持最新的稳定版。你也可以用其它 Docker 服务来更新。首先你需要pull镜像
```

View file

@ -15,6 +15,8 @@ menu:
# 用 Docker 安裝
{{< toc >}}
我們在 Docker Hub 提供了自動更新的映像檔,它會保持最新穩定版。根據您的部屬環境來使用最新版本或用其他服務來更新 Docker 映像檔。首先您需要下載映像檔:
```

View file

@ -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:

View file

@ -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

View file

@ -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.