跳至主要内容
版本:1.24.5

外部渲染器

Gitea 通過外部二進制文件支持自定义文件渲染(例如 Jupyter notebooks、asciidoc 等),只需要進行以下步骤:

  • 安裝外部二進制文件
  • 在您的 app.ini 文件中添加一些配置
  • 重新启动 Gitea 实例

此功能支持整个文件的渲染。如果您想要在 Markdown 中渲染代码块,您需要使用 JavaScript 進行一些操作。請参阅 自定义 Gitea 配置 页面上的一些示例。

安裝外部二進制文件

為了通過外部二進制文件進行文件渲染,必須安裝它们的关联軟體包。 如果您正在使用 Docker 镜像,则您的 Dockerfile 應該包含以下内容:

FROM docker.gitea.com/gitea:1.24.5
[...]

COPY custom/app.ini /data/gitea/conf/app.ini
[...]

RUN apk --no-cache add asciidoctor freetype freetype-dev gcc g++ libpng libffi-dev pandoc python3-dev py3-pyzmq pipx
# 安裝其他您需要的外部渲染器的軟體包

RUN pipx install jupyter docutils --include-deps
# 在上面添加您需要安裝的任何其他 Python 軟體包

app.ini 文件配置

在您的自定义 app.ini 文件中為每个外部渲染器添加一个 [markup.XXXXX] 部分:

[markup.asciidoc]
ENABLED = true
FILE_EXTENSIONS = .adoc,.asciidoc
RENDER_COMMAND = "asciidoctor -s -a showtitle --out-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

如果您的外部标记语言依赖于在生成的 HTML 元素上的额外类和属性,您可能需要启用自定义的清理策略。Gitea 使用 bluemonday 包作為我们的 HTML 清理器。下面的示例可以用于支持从 pandoc 输出的服务器端 KaTeX 渲染结果。

[markup.sanitizer.TeX]
; Pandoc 渲染 TeX 段落為带有 "math" 类的 <span> 元素,根据上下文可能還带有 "inline" 或 "display" 类。
; - 請注意,这与我们的 Markdown 解析器中内置的数学支持不同,后者使用 <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

您必須在每个部分中定义 ELEMENTALLOW_ATTR

要定义多个条目,請添加唯一的字母数字后缀(例如,[markup.sanitizer.1][markup.sanitizer.something])。

要僅為特定的外部渲染器應用清理規則,它们必須使用渲染器名稱,例如 [markup.sanitizer.asciidoc.rule-1][markup.sanitizer.<renderer>.rule-1]

注意:如果規則在渲染器 ini 部分之前定义,或者名稱与渲染器不匹配,它将應用于所有渲染器。

完成配置更改后,請重新启动 Gitea 以使更改生效。

注意:在 Gitea 1.12 之前,存在一个名為 markup.sanitiser 的單个部分,其中的键被重新定义為多个規則,但是,这种配置方法存在重大问题,需要通過多个部分進行配置。

示例:HTML

直接渲染 HTML 文件:

[markup.html]
ENABLED = true
FILE_EXTENSIONS = .html,.htm
RENDER_COMMAND = cat
; 输入不是标准输入,而是文件
IS_INPUT_FILE = true

[markup.sanitizer.html.1]
ELEMENT = div
ALLOW_ATTR = class

[markup.sanitizer.html.2]
ELEMENT = a
ALLOW_ATTR = class

請注意:此示例中的配置将允许渲染 HTML 文件,並使用 cat 命令将文件内容输出為 HTML。此外,配置中的两个清理規則将允许 <div><a> 元素使用 class 属性。

在進行配置更改后,請重新启动 Gitea 以使更改生效。

示例:Office DOCX

使用 pandoc 显示 Office DOCX 文件:

[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

在此示例中,配置将允许显示 Office DOCX 文件,並使用 pandoc 命令将文件转换為 HTML 格式。同时,清理規則中的 ALLOW_DATA_URI_IMAGES 设置為 true,允许使用 Data URI 格式的图片。

模板文件的内容如下:

$body$

示例:Jupyter Notebook

使用 nbconvert 显示 Jupyter Notebook 文件:

[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

在此示例中,配置将允许显示 Jupyter Notebook 文件,並使用 nbconvert 命令将文件转换為 HTML 格式。同样,清理規則中的 ALLOW_DATA_URI_IMAGES 设置為 true,允许使用 Data URI 格式的图片。

在進行配置更改后,請重新启动 Gitea 以使更改生效。

自定义 CSS

.ini 文件中,可以使用 [markup.XXXXX] 的格式指定外部渲染器,並且由外部渲染器生成的 HTML 将被包装在一个带有 markupXXXXX 类的 <div> 中。markup 类提供了预定义的样式(如果 XXXXXmarkdown,则使用 markdown 类)。否则,您可以使用这些类来针对渲染的 HTML 内容進行定制样式。

因此,您可以编写一些 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;
}

将您的样式表添加到自定义目錄中,例如 custom/public/assets/css/my-style-XXXXX.css,並使用自定义的头文件 custom/templates/custom/header.tmpl 進行导入:

<link rel="stylesheet" href="{{AppSubUrl}}/assets/css/my-style-XXXXX.css" />

通過以上步骤,您可以将自定义的 CSS 样式應用到特定的外部渲染器,使其具有所需的样式效果。