From 6bdcacd73b403354aa180bfada7236038d9712b1 Mon Sep 17 00:00:00 2001 From: 6543 <6543@obermui.de> Date: Tue, 8 Dec 2020 04:52:26 +0000 Subject: [PATCH] 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 --- .../doc/advanced/config-cheat-sheet.en-us.md | 2 ++ .../doc/advanced/config-cheat-sheet.zh-cn.md | 2 ++ .../doc/advanced/customizing-gitea.en-us.md | 4 +++ .../advanced/logging-documentation.en-us.md | 2 ++ .../content/doc/advanced/mail-templates-us.md | 6 ++-- .../content/doc/developers/api-usage.en-us.md | 8 +++-- .../doc/developers/hacking-on-gitea.en-us.md | 6 ++-- .../doc/features/authentication.en-us.md | 2 ++ docs/content/doc/help/faq.en-us.md | 32 +------------------ .../database-preparation.en-us.md | 4 +++ .../doc/installation/from-binary.en-us.md | 10 ++++-- .../doc/installation/from-package.en-us.md | 2 ++ .../doc/installation/from-source.en-us.md | 2 ++ .../doc/installation/with-docker.en-us.md | 2 ++ .../doc/installation/with-docker.fr-fr.md | 2 ++ .../doc/installation/with-docker.zh-cn.md | 2 ++ .../doc/installation/with-docker.zh-tw.md | 2 ++ docs/content/doc/usage/command-line.en-us.md | 32 ++++++++++--------- .../doc/usage/linked-references.en-us.md | 2 ++ .../doc/usage/reverse-proxies.en-us.md | 24 ++++++++------ 20 files changed, 82 insertions(+), 66 deletions(-) diff --git a/docs/content/doc/advanced/config-cheat-sheet.en-us.md b/docs/content/doc/advanced/config-cheat-sheet.en-us.md index 8427523f63..eade821186 100644 --- a/docs/content/doc/advanced/config-cheat-sheet.en-us.md +++ b/docs/content/doc/advanced/config-cheat-sheet.en-us.md @@ -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. diff --git a/docs/content/doc/advanced/config-cheat-sheet.zh-cn.md b/docs/content/doc/advanced/config-cheat-sheet.zh-cn.md index 597773a0ae..9ba46e3579 100644 --- a/docs/content/doc/advanced/config-cheat-sheet.zh-cn.md +++ b/docs/content/doc/advanced/config-cheat-sheet.zh-cn.md @@ -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`: 应用名称，改成你希望的名字。 diff --git a/docs/content/doc/advanced/customizing-gitea.en-us.md b/docs/content/doc/advanced/customizing-gitea.en-us.md index 474c7274eb..718e3c6d99 100644 --- a/docs/content/doc/advanced/customizing-gitea.en-us.md +++ b/docs/content/doc/advanced/customizing-gitea.en-us.md @@ -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 diff --git a/docs/content/doc/advanced/logging-documentation.en-us.md b/docs/content/doc/advanced/logging-documentation.en-us.md index aa5dacea99..8f6a5b79bf 100644 --- a/docs/content/doc/advanced/logging-documentation.en-us.md +++ b/docs/content/doc/advanced/logging-documentation.en-us.md @@ -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 diff --git a/docs/content/doc/advanced/mail-templates-us.md b/docs/content/doc/advanced/mail-templates-us.md index dab1b6cbaa..1d1423122a 100644 --- a/docs/content/doc/advanced/mail-templates-us.md +++ b/docs/content/doc/advanced/mail-templates-us.md @@ -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](#). > diff --git a/docs/content/doc/developers/api-usage.en-us.md b/docs/content/doc/developers/api-usage.en-us.md index 5e979d1e94..7dc6406a23 100644 --- a/docs/content/doc/developers/api-usage.en-us.md +++ b/docs/content/doc/developers/api-usage.en-us.md @@ -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: diff --git a/docs/content/doc/developers/hacking-on-gitea.en-us.md b/docs/content/doc/developers/hacking-on-gitea.en-us.md index 6eda456ce2..2c331faf63 100644 --- a/docs/content/doc/developers/hacking-on-gitea.en-us.md +++ b/docs/content/doc/developers/hacking-on-gitea.en-us.md @@ -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: diff --git a/docs/content/doc/features/authentication.en-us.md b/docs/content/doc/features/authentication.en-us.md index 7b295dd1d1..d91aa68c25 100644 --- a/docs/content/doc/features/authentication.en-us.md +++ b/docs/content/doc/features/authentication.en-us.md @@ -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: diff --git a/docs/content/doc/help/faq.en-us.md b/docs/content/doc/help/faq.en-us.md index eb8efcd429..9c7211937b 100644 --- a/docs/content/doc/help/faq.en-us.md +++ b/docs/content/doc/help/faq.en-us.md @@ -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. diff --git a/docs/content/doc/installation/database-preparation.en-us.md b/docs/content/doc/installation/database-preparation.en-us.md index df078b01df..32cfe18120 100644 --- a/docs/content/doc/installation/database-preparation.en-us.md +++ b/docs/content/doc/installation/database-preparation.en-us.md @@ -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: diff --git a/docs/content/doc/installation/from-binary.en-us.md b/docs/content/doc/installation/from-binary.en-us.md index 794b165f63..aac10d577d 100644 --- a/docs/content/doc/installation/from-binary.en-us.md +++ b/docs/content/doc/installation/from-binary.en-us.md @@ -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 diff --git a/docs/content/doc/installation/from-package.en-us.md b/docs/content/doc/installation/from-package.en-us.md index c2e0924962..91c57a80fa 100644 --- a/docs/content/doc/installation/from-package.en-us.md +++ b/docs/content/doc/installation/from-package.en-us.md @@ -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. diff --git a/docs/content/doc/installation/from-source.en-us.md b/docs/content/doc/installation/from-source.en-us.md index 125deb8248..5fc521204d 100644 --- a/docs/content/doc/installation/from-source.en-us.md +++ b/docs/content/doc/installation/from-source.en-us.md @@ -36,6 +36,8 @@ obtain the same version as our continuous integration, see the advice given in Hacking on Gitea +{{< toc >}} + ## Download First, we must retrieve the source code. Since, the advent of go modules, the diff --git a/docs/content/doc/installation/with-docker.en-us.md b/docs/content/doc/installation/with-docker.en-us.md index 9f8d88d1a8..ac085e4efc 100644 --- a/docs/content/doc/installation/with-docker.en-us.md +++ b/docs/content/doc/installation/with-docker.en-us.md @@ -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` diff --git a/docs/content/doc/installation/with-docker.fr-fr.md b/docs/content/doc/installation/with-docker.fr-fr.md index 0bce615749..418615e986 100644 --- a/docs/content/doc/installation/with-docker.fr-fr.md +++ b/docs/content/doc/installation/with-docker.fr-fr.md @@ -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 : diff --git a/docs/content/doc/installation/with-docker.zh-cn.md b/docs/content/doc/installation/with-docker.zh-cn.md index add51867a3..7fe6132fb8 100644 --- a/docs/content/doc/installation/with-docker.zh-cn.md +++ b/docs/content/doc/installation/with-docker.zh-cn.md @@ -17,6 +17,8 @@ menu: 阅读本章之前我们已经假设您对docker已经有了解并能够正常使用docker。 +{{< toc >}} + 我们在 Docker Hub 的 Gitea 组织中提供了自动更新的 Docker 镜像，它会保持最新的稳定版。你也可以用其它 Docker 服务来更新。首先你需要pull镜像： ``` diff --git a/docs/content/doc/installation/with-docker.zh-tw.md b/docs/content/doc/installation/with-docker.zh-tw.md index 5d98c43a43..b4c95c1ba2 100644 --- a/docs/content/doc/installation/with-docker.zh-tw.md +++ b/docs/content/doc/installation/with-docker.zh-tw.md @@ -15,6 +15,8 @@ menu: # 用 Docker 安裝 +{{< toc >}} + 我們在 Docker Hub 提供了自動更新的映像檔，它會保持最新穩定版。根據您的部屬環境來使用最新版本或用其他服務來更新 Docker 映像檔。首先您需要下載映像檔： ``` diff --git a/docs/content/doc/usage/command-line.en-us.md b/docs/content/doc/usage/command-line.en-us.md index 34ba6cdb2d..0867b3d16f 100644 --- a/docs/content/doc/usage/command-line.en-us.md +++ b/docs/content/doc/usage/command-line.en-us.md @@ -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: diff --git a/docs/content/doc/usage/linked-references.en-us.md b/docs/content/doc/usage/linked-references.en-us.md index bbfd1ef64e..963d54fad5 100644 --- a/docs/content/doc/usage/linked-references.en-us.md +++ b/docs/content/doc/usage/linked-references.en-us.md @@ -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 diff --git a/docs/content/doc/usage/reverse-proxies.en-us.md b/docs/content/doc/usage/reverse-proxies.en-us.md index 1ca73c3657..89f7ff5c4e 100644 --- a/docs/content/doc/usage/reverse-proxies.en-us.md +++ b/docs/content/doc/usage/reverse-proxies.en-us.md @@ -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.