Use docusaurus warning/note syntax instead markdown

2024-06-07 18:03:08 +08:00
parent 91cd95dba0
commit b4dddf8804
139 changed files with 860 additions and 341 deletions
@@ -24,7 +24,9 @@ inside the `custom` directory (see [Customizing Gitea](administration/customizin
 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

@@ -33,7 +33,9 @@ In the default values below, a value in the form `$XYZ` refers to an environment

 Values containing `#` or `;` must be quoted using `` ` `` or `"""`.

-**Note:** A full restart is required for Gitea configuration changes to take effect.
+:::info
+A full restart is required for Gitea configuration changes to take effect.
+:::

 ## Default Configuration (non-`app.ini` configuration)

@@ -96,8 +98,12 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build
 - `GO_GET_CLONE_URL_PROTOCOL`: **https**: Value for the "go get" request returns the repository url as https or ssh
   default is https.
 - `ACCESS_CONTROL_ALLOW_ORIGIN`: **_empty_**: Value for Access-Control-Allow-Origin header,
-   default is not to present. **WARNING**: This maybe harmful to you website if you do not
-   give it a right value.
+   default is not to present.
+
+   :::warning
+   This maybe harmful to you website if you do not give it a right value.
+   :::
+
 - `DEFAULT_CLOSE_ISSUES_VIA_COMMITS_IN_ANY_BRANCH`:  **false**: Close an issue if a commit on a non default branch marks it as closed.
 - `ENABLE_PUSH_CREATE_USER`:  **false**: Allow users to push local repositories to Gitea and have them automatically created for a user.
 - `ENABLE_PUSH_CREATE_ORG`:  **false**: Allow users to push local repositories to Gitea and have them automatically created for an org.
@@ -544,13 +550,17 @@ And the following unique queues:
   Number of trusted proxy count. Set to zero to not use these headers.
 - `REVERSE_PROXY_TRUSTED_PROXIES`: **127.0.0.0/8,::1/128**: List of IP addresses and networks separated by comma of trusted proxy servers. Use `*` to trust all.
 - `DISABLE_GIT_HOOKS`: **true**: Set to `false` to enable users with Git Hook privilege to create custom Git Hooks.
-   WARNING: Custom Git Hooks can be used to perform arbitrary code execution on the host operating system.
-   This enables the users to access and modify this config file and the Gitea database and interrupt the Gitea service.
-   By modifying the Gitea database, users can gain Gitea administrator privileges.
-   It also enables them to access other resources available to the user on the operating system that is running the
-   Gitea instance and perform arbitrary actions in the name of the Gitea OS user.
-   This maybe harmful to you website or your operating system.
-   Setting this to true does not change existing hooks in git repos; adjust it before if necessary.
+
+  :::warning
+  Custom Git Hooks can be used to perform arbitrary code execution on the host operating system.
+  This enables the users to access and modify this config file and the Gitea database and interrupt the Gitea service.
+  By modifying the Gitea database, users can gain Gitea administrator privileges.
+  It also enables them to access other resources available to the user on the operating system that is running the
+  Gitea instance and perform arbitrary actions in the name of the Gitea OS user.
+  This maybe harmful to you website or your operating system.
+  Setting this to true does not change existing hooks in git repos; adjust it before if necessary.
+  :::
+
 - `DISABLE_WEBHOOKS`: **false**: Set to `true` to disable webhooks feature.
 - `ONLY_ALLOW_PUSH_IF_GITEA_ENVIRONMENT_SET`: **true**: Set to `false` to allow local users to push to gitea-repositories without setting up the Gitea environment. This is not recommended and if you want local users to push to Gitea repositories you should set the environment appropriately.
 - `IMPORT_LOCAL_PATHS`: **false**: Set to `false` to prevent all users (including admin) from importing local path on server.
@@ -632,8 +642,12 @@ And the following unique queues:
 - `DISABLE_REGISTRATION`: **false**: Disable registration, after which only admin can create
   accounts for users.
 - `REQUIRE_EXTERNAL_REGISTRATION_PASSWORD`: **false**: Enable this to force externally created
-   accounts (via GitHub, OpenID Connect, etc) to create a password. Warning: enabling this will
-   decrease security, so you should only enable it if you know what you're doing.
+   accounts (via GitHub, OpenID Connect, etc) to create a password.
+
+   :::warning
+   Enabling this will decrease security, so you should only enable it if you know what you're doing.
+   :::
+
 - `REQUIRE_SIGNIN_VIEW`: **false**: Enable this to force users to log in to view any page or to use API.
 - `ENABLE_NOTIFY_MAIL`: **false**: Enable this to send e-mail to watchers of a repository when
   something happens, like creating issues. Requires `Mailer` to be enabled.
@@ -1238,7 +1252,9 @@ in this mapping or the filetype using heuristics.
 - `SHARE_USER_STATISTICS`: **true**: Enable/Disable user statistics for nodeinfo if federation is enabled
 - `MAX_SIZE`: **4**: Maximum federation request and response size (MB)

- WARNING: Changing the settings below can break federation.
+  :::warning
+  Changing the settings below can break federation.
+  :::

 - `ALGORITHMS`: **rsa-sha256, rsa-sha512, ed25519**: HTTP signature algorithms
 - `DIGEST_ALGORITHM`: **SHA-256**: HTTP signature digest algorithm
@@ -46,7 +46,9 @@ is set under the "Configuration" tab on the site administration page.

 - [List of Environment Variables](administration/environment-variables.md)

-**Note:** Gitea must perform a full restart to see configuration changes.
+:::note
+Gitea must perform a full restart to see configuration changes.
+:::

 ## Serving custom public files

@@ -288,7 +290,9 @@ Google Analytics, Matomo (previously Piwik), and other analytics services can be

 Place custom files in corresponding sub-folder under `custom/options`.

-**NOTE:** The files should not have a file extension, e.g. `Labels` rather than `Labels.txt`
+:::note
+The files should not have a file extension, e.g. `Labels` rather than `Labels.txt`
+:::

 ### gitignores

@@ -340,7 +344,7 @@ Gitea's default locale files can be found in the [`options/locale`](https://gith

 To add a completely new locale, as well as placing the file in the above location, you will need to add the new lang and name to the `[i18n]` section in your `app.ini`. Keep in mind that Gitea will use those settings as **overrides**, so if you want to keep the other languages as well you will need to copy/paste the default values and add your own to them.

-```
+```ini title="app.ini"
 [i18n]
 LANGS = en-US,foo-BAR
 NAMES = English,FooBar
@@ -354,14 +358,16 @@ Locales may change between versions, so keeping track of your customized locales

 To add a custom Readme, add a markdown formatted file (without an `.md` extension) to `$GITEA_CUSTOM/options/readme`

-**NOTE:** readme templates support **variable expansion**.
+:::note
+Readme templates support **variable expansion**.
 currently there are `{Name}` (name of repository), `{Description}`, `{CloneURL.SSH}`, `{CloneURL.HTTPS}` and `{OwnerName}`
+:::

 ### Reactions

 To change reaction emoji's you can set allowed reactions at app.ini

-```
+```ini title="app.ini"
 [ui]
 REACTIONS = +1, -1, laugh, confused, heart, hooray, eyes
 ```
@@ -23,9 +23,13 @@ Gitea has mailer functionality for sending transactional emails (such as registr

 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 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.
+:::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]
@@ -57,7 +61,9 @@ To send a test email to validate the settings, go to Gitea > Site Administration

 For the full list of options check the [Config Cheat Sheet](administration/config-cheat-sheet.md)

-Please note: authentication is only supported when the SMTP server communication is encrypted with TLS or `HOST=localhost`. TLS encryption can be through:
+:::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. 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.
@@ -29,4 +29,6 @@ LFS_START_SERVER = true
 PATH = /home/gitea/data/lfs
 ```

-**Note**: LFS server support needs at least Git v2.1.2 installed on the server
+:::note
+LFS server support needs at least Git v2.1.2 installed on the server
+:::
@@ -97,4 +97,6 @@ After that, enable HTTPS by following one of these guides:
 - [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.
+:::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.
+:::
@@ -173,7 +173,9 @@ If you want Apache HTTPD to serve your Gitea instance, you can add the following
 </VirtualHost>
 ```

-Note: The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`.
+:::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.

@@ -198,7 +200,9 @@ In case you already have a site, and you want Gitea to share the domain name, yo

 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`.
+:::note
+The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`.
+:::

 ## Caddy