mirror of
https://github.com/go-gitea/gitea.git
synced 2024-08-31 00:27:47 +02:00
This was intended to be a small followup for https://github.com/go-gitea/gitea/pull/23712, but...here we are. 1. Our docs currently use `slug` as the entire URL, which makes refactoring tricky (see https://github.com/go-gitea/gitea/pull/23712). Instead, this PR attempts to make future refactoring easier by using slugs as an extension of the section. (Hugo terminology) - What the above boils down to is this PR attempts to use directory organization as URL management. e.g. `usage/comparison.en-us.md` -> `en-us/usage/comparison/`, `usage/packages/overview.en-us.md` -> `en-us/usage/packages/overview/` - Technically we could even remove `slug`, as Hugo defaults to using filename, however at least with this PR it means `slug` only needs to be the name for the **current file** rather than an entire URL 2. This PR adds appropriate aliases (redirects) for pages, so anything on the internet that links to our docs should hopefully not break. 3. A minor nit I've had for a while, renaming `seek-help` to `support`. It's a minor thing, but `seek-help` has a strange connotation to it. 4. The commits are split such that you can review the first which is the "actual" change, and the second is added redirects so that the first doesn't break links elsewhere. --------- Signed-off-by: jolheiser <john.olheiser@gmail.com>
199 lines
5.9 KiB
Markdown
199 lines
5.9 KiB
Markdown
---
|
|
date: "2018-11-23:00:00+02:00"
|
|
title: "External renderers"
|
|
slug: "external-renderers"
|
|
weight: 60
|
|
toc: false
|
|
draft: false
|
|
aliases:
|
|
- /en-us/external-renderers
|
|
menu:
|
|
sidebar:
|
|
parent: "administration"
|
|
name: "External renderers"
|
|
weight: 60
|
|
identifier: "external-renderers"
|
|
---
|
|
|
|
# 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
|
|
|
|
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/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" />
|
|
```
|