Reformat/fine-tune docs

docs/content/doc/advanced/cmd-embedded.en-us.md

@@ -3,7 +3,7 @@ date: "2020-01-25T21:00:00-03:00"
 title: "Embedded data extraction tool"
 slug: "cmd-embedded"
 weight: 40
-toc: true
+toc: false
 draft: false
 menu:
   sidebar:
@@ -15,6 +15,10 @@ menu:
 
 # Embedded data extraction tool
 
+**Table of Contents**
+
+{{< toc >}}
+
 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]({{< relref "doc/advanced/customizing-gitea.en-us.md" >}})).
@@ -28,7 +32,7 @@ can be used from the OS shell interface.
 
 To list resources embedded in Gitea's executable, use the following syntax:
 
-```
+```sh
 gitea embedded list [--include-vendored] [patterns...]
 ```
 
@@ -48,11 +52,11 @@ a special meaning for your command shell.
 
 If no pattern is provided, all files are listed.
 
-#### Example
+### Example
 
 Listing all embedded files with `openid` in their path:
 
-```
+```sh
 $ gitea embedded list '**openid**'
 public/img/auth/openid_connect.svg
 public/img/openid-16x16.png
@@ -68,7 +72,7 @@ templates/user/settings/security_openid.tmpl
 
 To extract resources embedded in Gitea's executable, use the following syntax:
 
-```
+```sh
 gitea [--config {file}] embedded extract [--destination {dir}|--custom] [--overwrite|--rename] [--include-vendored] {patterns...}
 ```
 
@@ -91,19 +95,19 @@ as `filename.bak`. Previous `.bak` files are overwritten.
 At least one file search pattern must be provided; see `list` subcomand above for pattern
 syntax and examples.
 
-#### Important notice
+### Important notice
 
 Make sure to **only extract those files that require customization**. Files that
 are present in the `custom` directory are not upgraded by Gitea's upgrade process.
 When Gitea is upgraded to a new version (by replacing the executable), many of the
 embedded files will suffer changes. Gitea will honor and use any files found
 in the `custom` directory, even if they are old and incompatible.
 
-#### Example
+### Example
 
 Extracting mail templates to a temporary directory:
 
-```
+```sh
 $ mkdir tempdir
 $ gitea embedded extract --destination tempdir 'templates/mail/**.tmpl'
 Extracting to tempdir:

docs/content/doc/advanced/customizing-gitea.en-us.md

@@ -45,7 +45,7 @@ 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
+**Table of Contents**
 
 {{< toc >}}
 
@@ -127,8 +127,8 @@ copy javascript files from https://gitea.com/davidsvantesson/plantuml-code-highl
 <script src="https://your-server.com/encode.js"></script>
 <script src="https://your-server.com/plantuml_codeblock_parse.js"></script>
 <script>
-<!-- Replace call with address to your plantuml server-->
-parsePlantumlCodeBlocks("http://www.plantuml..com/plantuml")
+  <!-- Replace call with address to your plantuml server-->
+  parsePlantumlCodeBlocks("http://www.plantuml..com/plantuml");
 </script>
 {{end}}
 ```
@@ -148,38 +148,50 @@ The script will detect tags with `class="language-plantuml"`, but you can change
 #### Example: STL Preview
 
 You can display STL file directly in Gitea by adding:
+
 ```html
 <script>
-function lS(src){
-  return new Promise(function(resolve, reject) {
-    let s = document.createElement('script')
-    s.src = src
-    s.addEventListener('load', () => {
-      resolve()
-    })
-    document.body.appendChild(s)
-  });
-}
-
-if($('.view-raw>a[href$=".stl" i]').length){
-  $('body').append('<link href="/Madeleine.js/src/css/Madeleine.css" rel="stylesheet">');
-  Promise.all([lS("/Madeleine.js/src/lib/stats.js"),lS("/Madeleine.js/src/lib/detector.js"), lS("/Madeleine.js/src/lib/three.min.js"), lS("/Madeleine.js/src/Madeleine.js")]).then(function() {
-    $('.view-raw').attr('id', 'view-raw').attr('style', 'padding: 0;margin-bottom: -10px;');
-    new Madeleine({
-      target: 'view-raw',
-      data: $('.view-raw>a[href$=".stl" i]').attr('href'),
-      path: '/Madeleine.js/src'
+  function lS(src) {
+    return new Promise(function (resolve, reject) {
+      let s = document.createElement("script");
+      s.src = src;
+      s.addEventListener("load", () => {
+        resolve();
+      });
+      document.body.appendChild(s);
     });
-    $('.view-raw>a[href$=".stl"]').remove()
-  });
-}
+  }
+
+  if ($('.view-raw>a[href$=".stl" i]').length) {
+    $("body").append(
+      '<link href="/Madeleine.js/src/css/Madeleine.css" rel="stylesheet">'
+    );
+    Promise.all([
+      lS("/Madeleine.js/src/lib/stats.js"),
+      lS("/Madeleine.js/src/lib/detector.js"),
+      lS("/Madeleine.js/src/lib/three.min.js"),
+      lS("/Madeleine.js/src/Madeleine.js"),
+    ]).then(function () {
+      $(".view-raw")
+        .attr("id", "view-raw")
+        .attr("style", "padding: 0;margin-bottom: -10px;");
+      new Madeleine({
+        target: "view-raw",
+        data: $('.view-raw>a[href$=".stl" i]').attr("href"),
+        path: "/Madeleine.js/src",
+      });
+      $('.view-raw>a[href$=".stl"]').remove();
+    });
+  }
 </script>
 ```
+
 to the file `templates/custom/footer.tmpl`
 
 You also need to download the content of the library [Madeleine.js](https://jinjunho.github.io/Madeleine.js/) and place it under `custom/public/` folder.
 
 You should end-up with a folder structucture similar to:
+
 ```
 custom/templates
 -- custom
@@ -267,7 +279,7 @@ To add a custom license, add a file with the license text to `custom/options/lic
 
 Locales are managed via our [crowdin](https://crowdin.com/project/gitea).  
 You can override a locale by placing an altered locale file in `custom/options/locale`.  
-Gitea's default locale files can be found in  the [`options/locale`](https://github.com/go-gitea/gitea/tree/master/options/locale) source folder and these should be used as examples for your changes.  
+Gitea's default locale files can be found in the [`options/locale`](https://github.com/go-gitea/gitea/tree/master/options/locale) source folder and these should be used as examples for your changes.
 
 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.
 
@@ -289,10 +301,12 @@ currently there are `{Name}` (name of repository), `{Description}`, `{CloneURL.S
 ### Reactions
 
 To change reaction emoji's you can set allowed reactions at app.ini
+
 ```
 [ui]
 REACTIONS = +1, -1, laugh, confused, heart, hooray, eyes
 ```
+
 A full list of supported emoji's is at [emoji list](https://gitea.com/gitea/gitea.com/issues/8)
 
 ## Customizing the look of Gitea

docs/content/doc/advanced/environment-variables.en-us.md

@@ -15,54 +15,58 @@ menu:
 
 # Environment variables
 
+**Table of Contents**
+
+{{< toc >}}
+
 This is an inventory of Gitea environment variables. They change Gitea behaviour.
 
 Initialize them before Gitea command to be effective, for example:
 
-```
+```sh
 GITEA_CUSTOM=/home/gitea/custom ./gitea web
 ```
 
 ## From Go language
 
 As Gitea is written in Go, it uses some Go variables, such as:
 
-  * `GOOS`
-  * `GOARCH`
-  * [`GOPATH`](https://golang.org/cmd/go/#hdr-GOPATH_environment_variable)
+- `GOOS`
+- `GOARCH`
+- [`GOPATH`](https://golang.org/cmd/go/#hdr-GOPATH_environment_variable)
 
 For documentation about each of the variables available, refer to the
 [official Go documentation](https://golang.org/cmd/go/#hdr-Environment_variables).
 
 ## Gitea files
 
-  * `GITEA_WORK_DIR`: Absolute path of working directory.
-  * `GITEA_CUSTOM`: Gitea uses `GITEA_WORK_DIR`/custom folder by default. Use this variable
-     to change *custom* directory.
-  * `GOGS_WORK_DIR`: Deprecated, use `GITEA_WORK_DIR`
-  * `GOGS_CUSTOM`: Deprecated, use `GITEA_CUSTOM`
+- `GITEA_WORK_DIR`: Absolute path of working directory.
+- `GITEA_CUSTOM`: Gitea uses `GITEA_WORK_DIR`/custom folder by default. Use this variable
+  to change _custom_ directory.
+- `GOGS_WORK_DIR`: Deprecated, use `GITEA_WORK_DIR`
+- `GOGS_CUSTOM`: Deprecated, use `GITEA_CUSTOM`
 
 ## Operating system specifics
 
-  * `USER`: System user that Gitea will run as. Used for some repository access strings.
-  * `USERNAME`: if no `USER` found, Gitea will use `USERNAME`
-  * `HOME`: User home directory path. The `USERPROFILE` environment variable is used in Windows.
+- `USER`: System user that Gitea will run as. Used for some repository access strings.
+- `USERNAME`: if no `USER` found, Gitea will use `USERNAME`
+- `HOME`: User home directory path. The `USERPROFILE` environment variable is used in Windows.
 
 ### Only on Windows
 
-  * `USERPROFILE`: User home directory path. If empty, uses `HOMEDRIVE` + `HOMEPATH`
-  * `HOMEDRIVE`: Main drive path used to access the home directory (C:)
-  * `HOMEPATH`: Home relative path in the given home drive path
+- `USERPROFILE`: User home directory path. If empty, uses `HOMEDRIVE` + `HOMEPATH`
+- `HOMEDRIVE`: Main drive path used to access the home directory (C:)
+- `HOMEPATH`: Home relative path in the given home drive path
 
 ## Macaron (framework used by Gitea)
 
-  * `HOST`: Host Macaron will listen on
-  * `PORT`: Port Macaron will listen on
-  * `MACARON_ENV`: global variable to provide special functionality for development environments
-     vs. production environments. If MACARON_ENV is set to "" or "development", then templates will
-     be recompiled on every request. For more performance, set the MACARON_ENV environment variable
-     to "production".
+- `HOST`: Host Macaron will listen on
+- `PORT`: Port Macaron will listen on
+- `MACARON_ENV`: global variable to provide special functionality for development environments
+  vs. production environments. If MACARON_ENV is set to "" or "development", then templates will
+  be recompiled on every request. For more performance, set the MACARON_ENV environment variable
+  to "production".
 
 ## Miscellaneous
 
-  * `SKIP_MINWINSVC`: If set to 1, do not run as a service on Windows.
+- `SKIP_MINWINSVC`: If set to 1, do not run as a service on Windows.

docs/content/doc/advanced/external-renderers.en-us.md

@@ -3,7 +3,7 @@ date: "2018-11-23:00:00+02:00"
 title: "External renderers"
 slug: "external-renderers"
 weight: 40
-toc: true
+toc: false
 draft: false
 menu:
   sidebar:
@@ -15,12 +15,16 @@ menu:
 
 # Custom files rendering configuration
 
+**Table of Contents**
+
+{{< toc >}}
+
 Gitea supports custom file renderings (i.e., Jupyter notebooks, asciidoc, etc.) through external binaries,
 it is just a matter of:
 
-* installing external binaries
-* add some configuration to your `app.ini` file
-* restart your Gitea instance
+- installing external binaries
+- 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](../customizing-gitea) page.
 
@@ -29,7 +33,7 @@ This supports rendering of whole files. If you want to render code blocks in mar
 In order to get file rendering through external binaries, their associated packages must be installed.
 If you're using a Docker image, your `Dockerfile` should contain something along this lines:
 
-```
+```docker
 FROM gitea/gitea:{{< version >}}
 [...]
 
@@ -49,7 +53,7 @@ RUN pip3 install jupyter docutils
 
 add one `[markup.XXXXX]` section per external renderer on your custom `app.ini`:
 
-```
+```ini
 [markup.asciidoc]
 ENABLED = true
 FILE_EXTENSIONS = .adoc,.asciidoc