Docusaurus-ify (#26051)

This PR cleans up the docs in a way to make them simpler to ingest by
our [docs repo](https://gitea.com/gitea/gitea-docusaurus).

1. It includes all of the sed invocations our ingestion did, removing
the need to do it at build time.
2. It replaces the shortcode variable replacement method with
`@variable@` style, simply for easier sed invocations when required.
3. It removes unused files and moves the docs up a level as cleanup.

---------

Signed-off-by: jolheiser <john.olheiser@gmail.com>

1 files changed, 194 insertions, 0 deletions

diff --git a/docs/content/administration/external-renderers.en-us.md b/docs/content/administration/external-renderers.en-us.md
new file mode 100644
index 0000000000..f903a7e760
--- /dev/null
+++ b/docs/content/administration/external-renderers.en-us.md
@@ -0,0 +1,194 @@
+---
+date: "2018-11-23:00:00+02:00"
+title: "External renderers"
+slug: "external-renderers"
+sidebar_position: 60
+toc: false
+draft: false
+aliases:
+  - /en-us/external-renderers
+menu:
+  sidebar:
+    parent: "administration"
+    name: "External renderers"
+    sidebar_position: 60
+    identifier: "external-renderers"
+---
+
+# Custom files rendering configuration
+
+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
+
+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.
+
+## Installing external binaries
+
+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@
+[...]
+
+COPY custom/app.ini /data/gitea/conf/app.ini
+[...]
+
+RUN apk --no-cache add asciidoctor freetype freetype-dev gcc g++ libpng libffi-dev py-pip python3-dev py3-pip py3-pyzmq
+# install any other package you need for your external renderers
+
+RUN pip3 install --upgrade pip
+RUN pip3 install -U setuptools
+RUN pip3 install jupyter docutils
+# add above any other python package you may need to install
+```
+
+## `app.ini` file configuration
+
+add one `[markup.XXXXX]` section per external renderer on your custom `app.ini`:
+
+```ini
+[markup.asciidoc]
+ENABLED = true
+FILE_EXTENSIONS = .adoc,.asciidoc
+RENDER_COMMAND = "asciidoctor -s -a showtitle --out-file=- -"
+; Input is not a standard input but a file
+IS_INPUT_FILE = false
+
+[markup.jupyter]
+ENABLED = true
+FILE_EXTENSIONS = .ipynb
+RENDER_COMMAND = "jupyter nbconvert --stdin --stdout --to html --template basic"
+IS_INPUT_FILE = false
+
+[markup.restructuredtext]
+ENABLED = true
+FILE_EXTENSIONS = .rst
+RENDER_COMMAND = "timeout 30s pandoc +RTS -M512M -RTS -f rst"
+IS_INPUT_FILE = false
+```
+
+If your external markup relies on additional classes and attributes on the generated HTML elements, you might need to enable custom sanitizer policies. Gitea uses the [`bluemonday`](https://godoc.org/github.com/microcosm-cc/bluemonday) package as our HTML sanitizer. The example below could be used to support server-side [KaTeX](https://katex.org/) rendering output from [`pandoc`](https://pandoc.org/).
+
+```ini
+[markup.sanitizer.TeX]
+; Pandoc renders TeX segments as <span>s with the "math" class, optionally
+; with "inline" or "display" classes depending on context.
+; - note this is different from the built-in math support in our markdown parser which uses <code>
+ELEMENT = span
+ALLOW_ATTR = class
+REGEXP = ^\s*((math(\s+|$)|inline(\s+|$)|display(\s+|$)))+
+
+[markup.markdown]
+ENABLED         = true
+FILE_EXTENSIONS = .md,.markdown
+RENDER_COMMAND  = pandoc -f markdown -t html --katex
+```
+
+You must define `ELEMENT` and `ALLOW_ATTR` in each section.
+
+To define multiple entries, add a unique alphanumeric suffix (e.g., `[markup.sanitizer.1]` and `[markup.sanitizer.something]`).
+
+To apply a sanitisation rules only for a specify external renderer they must use the renderer name, e.g. `[markup.sanitizer.asciidoc.rule-1]`, `[markup.sanitizer.<renderer>.rule-1]`.
+
+**Note**: If the rule is defined above the renderer ini section or the name does not match a renderer it is applied to every renderer.
+
+Once your configuration changes have been made, restart Gitea to have changes take effect.
+
+**Note**: Prior to Gitea 1.12 there was a single `markup.sanitiser` section with keys that were redefined for multiple rules, however,
+there were significant problems with this method of configuration necessitating configuration through multiple sections.
+
+### Example: HTML
+
+Render HTML files directly:
+
+```ini
+[markup.html]
+ENABLED         = true
+FILE_EXTENSIONS = .html,.htm
+RENDER_COMMAND  = cat
+; Input is not a standard input but a file
+IS_INPUT_FILE   = true
+
+[markup.sanitizer.html.1]
+ELEMENT = div
+ALLOW_ATTR = class
+
+[markup.sanitizer.html.2]
+ELEMENT = a
+ALLOW_ATTR = class
+```
+
+### Example: Office DOCX
+
+Display Office DOCX files with [`pandoc`](https://pandoc.org/):
+
+```ini
+[markup.docx]
+ENABLED = true
+FILE_EXTENSIONS = .docx
+RENDER_COMMAND = "pandoc --from docx --to html --self-contained --template /path/to/basic.html"
+
+[markup.sanitizer.docx.img]
+ALLOW_DATA_URI_IMAGES = true
+```
+
+The template file has the following content:
+
+```
+$body$
+```
+
+### Example: Jupyter Notebook
+
+Display Jupyter Notebook files with [`nbconvert`](https://github.com/jupyter/nbconvert):
+
+```ini
+[markup.jupyter]
+ENABLED = true
+FILE_EXTENSIONS = .ipynb
+RENDER_COMMAND = "jupyter-nbconvert --stdin --stdout --to html --template basic"
+
+[markup.sanitizer.jupyter.img]
+ALLOW_DATA_URI_IMAGES = true
+```
+
+## Customizing CSS
+
+The external renderer is specified in the .ini in the format `[markup.XXXXX]` and the HTML supplied by your external renderer will be wrapped in a `<div>` with classes `markup` and `XXXXX`. The `markup` class provides out of the box styling (as does `markdown` if `XXXXX` is `markdown`). Otherwise you can use these classes to specifically target the contents of your rendered HTML.
+
+And so you could write some CSS:
+
+```css
+.markup.XXXXX html {
+  font-size: 100%;
+  overflow-y: scroll;
+  -webkit-text-size-adjust: 100%;
+  -ms-text-size-adjust: 100%;
+}
+
+.markup.XXXXX body {
+  color: #444;
+  font-family: Georgia, Palatino, 'Palatino Linotype', Times, 'Times New Roman', serif;
+  font-size: 12px;
+  line-height: 1.7;
+  padding: 1em;
+  margin: auto;
+  max-width: 42em;
+  background: #fefefe;
+}
+
+.markup.XXXXX p {
+  color: orangered;
+}
+```
+
+Add your stylesheet to your custom directory e.g `custom/public/assets/css/my-style-XXXXX.css` and import it using a custom header file `custom/templates/custom/header.tmpl`:
+
+```html
+<link rel="stylesheet" href="{{AppSubUrl}}/assets/css/my-style-XXXXX.css" />
+```