2018-11-23 23:07:08 +08:00
---
date: "2018-11-23:00:00+02:00"
title: "External renderers"
slug: "external-renderers"
weight: 40
2020-12-09 14:47:06 +08:00
toc: false
2018-11-23 23:07:08 +08:00
draft: false
menu:
sidebar:
2023-03-23 23:18:24 +08:00
parent: "administration"
2018-11-23 23:07:08 +08:00
name: "External renderers"
2023-03-23 23:18:24 +08:00
weight: 60
2018-11-23 23:07:08 +08:00
identifier: "external-renderers"
---
# Custom files rendering configuration
2020-12-09 14:47:06 +08:00
**Table of Contents**
{{< toc > }}
2020-11-28 14:12:22 +08:00
Gitea supports custom file renderings (i.e., Jupyter notebooks, asciidoc, etc.) through external binaries,
2019-03-10 05:15:45 +08:00
it is just a matter of:
2019-08-08 12:47:57 +08:00
2020-12-09 14:47:06 +08:00
- installing external binaries
- add some configuration to your `app.ini` file
- restart your Gitea instance
2018-11-23 23:07:08 +08:00
2020-01-21 07:34:23 +08:00
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.
2018-11-23 23:07:08 +08:00
## Installing external binaries
2020-11-28 14:12:22 +08:00
In order to get file rendering through external binaries, their associated packages must be installed.
2018-11-23 23:07:08 +08:00
If you're using a Docker image, your `Dockerfile` should contain something along this lines:
2020-12-09 14:47:06 +08:00
```docker
2019-09-26 15:04:53 +08:00
FROM gitea/gitea:{{< version > }}
2018-11-23 23:07:08 +08:00
[...]
COPY custom/app.ini /data/gitea/conf/app.ini
[...]
2020-10-16 02:30:25 +08:00
RUN apk --no-cache add asciidoctor freetype freetype-dev gcc g++ libpng libffi-dev py-pip python3-dev py3-pip py3-pyzmq
2018-11-23 23:07:08 +08:00
# install any other package you need for your external renderers
RUN pip3 install --upgrade pip
RUN pip3 install -U setuptools
2020-11-28 14:12:22 +08:00
RUN pip3 install jupyter docutils
2018-11-23 23:07:08 +08:00
# 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` :
2020-12-09 14:47:06 +08:00
```ini
2018-11-23 23:07:08 +08:00
[markup.asciidoc]
ENABLED = true
FILE_EXTENSIONS = .adoc,.asciidoc
2020-09-02 23:01:28 +08:00
RENDER_COMMAND = "asciidoctor -s -a showtitle --out-file=- -"
2018-11-23 23:07:08 +08:00
; Input is not a standard input but a file
IS_INPUT_FILE = false
[markup.jupyter]
ENABLED = true
FILE_EXTENSIONS = .ipynb
2021-06-24 05:09:51 +08:00
RENDER_COMMAND = "jupyter nbconvert --stdin --stdout --to html --template basic"
IS_INPUT_FILE = false
2018-11-23 23:07:08 +08:00
[markup.restructuredtext]
ENABLED = true
FILE_EXTENSIONS = .rst
2021-04-30 14:50:55 +08:00
RENDER_COMMAND = "timeout 30s pandoc +RTS -M512M -RTS -f rst"
2018-11-23 23:07:08 +08:00
IS_INPUT_FILE = false
```
2022-09-14 00:33:37 +08:00
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/ ).
2019-12-08 03:49:04 +08:00
```ini
2020-04-29 19:34:59 +08:00
[markup.sanitizer.TeX]
2019-12-08 03:49:04 +08:00
; Pandoc renders TeX segments as < span > s with the "math" class, optionally
; with "inline" or "display" classes depending on context.
2022-09-14 00:33:37 +08:00
; - note this is different from the built-in math support in our markdown parser which uses < code >
2019-12-08 03:49:04 +08:00
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
```
2021-06-24 05:09:51 +08:00
You must define `ELEMENT` and `ALLOW_ATTR` in each section.
2020-04-29 19:34:59 +08:00
To define multiple entries, add a unique alphanumeric suffix (e.g., `[markup.sanitizer.1]` and `[markup.sanitizer.something]` ).
2019-12-08 03:49:04 +08:00
2021-06-24 05:09:51 +08:00
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.
2018-11-23 23:07:08 +08:00
Once your configuration changes have been made, restart Gitea to have changes take effect.
2020-04-29 19:34:59 +08:00
**Note**: Prior to Gitea 1.12 there was a single `markup.sanitiser` section with keys that were redefined for multiple rules, however,
2020-09-02 23:01:28 +08:00
there were significant problems with this method of configuration necessitating configuration through multiple sections.
2021-05-07 16:43:41 +08:00
2022-02-14 21:56:17 +08:00
### 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
```
2021-06-24 05:09:51 +08:00
### Example: Office DOCX
Display Office DOCX files with [`pandoc` ](https://pandoc.org/ ):
2022-07-28 09:22:47 +08:00
2021-06-24 05:09:51 +08:00
```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:
2022-07-28 09:22:47 +08:00
2021-06-24 05:09:51 +08:00
```
$body$
```
### Example: Jupyter Notebook
Display Jupyter Notebook files with [`nbconvert` ](https://github.com/jupyter/nbconvert ):
2022-07-28 09:22:47 +08:00
2021-06-24 05:09:51 +08:00
```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
```
2021-05-07 16:43:41 +08:00
## Customizing CSS
2022-07-28 09:22:47 +08:00
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.
2021-05-07 16:43:41 +08:00
And so you could write some CSS:
2022-07-28 09:22:47 +08:00
2021-05-07 16:43:41 +08:00
```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` :
2022-07-28 09:22:47 +08:00
2021-05-07 16:43:41 +08:00
```html
2023-01-14 07:25:15 +08:00
< link rel = "stylesheet" href = "{{AppSubUrl}}/assets/css/my-style-XXXXX.css" / >
2021-05-07 16:43:41 +08:00
```