mirror of
https://gitea.com/gitea/docs.git
synced 2026-09-20 04:58:52 +00:00
docs: update zh-tw (#197)
Signed-off-by: appleboy <[email protected]> Reviewed-on: https://gitea.com/gitea/docs/pulls/197 Co-authored-by: appleboy <[email protected]> Co-committed-by: appleboy <[email protected]>
This commit is contained in:
appleboy
+35
-38
@@ -6,21 +6,20 @@ aliases:
|
||||
- /zh-tw/external-renderers
|
||||
---
|
||||
|
||||
# External renderers
|
||||
# 外部渲染器
|
||||
|
||||
Gitea supports custom file renderings (i.e., Jupyter notebooks, asciidoc, etc.) through external binaries,
|
||||
it is just a matter of:
|
||||
Gitea 支援透過外部二進位檔案進行自訂檔案渲染（例如 Jupyter 筆記本、asciidoc 等），只需：
|
||||
|
||||
- installing external binaries
|
||||
- add some configuration to your `app.ini` file
|
||||
- restart your Gitea instance
|
||||
- 安裝外部二進位檔案
|
||||
- 在 `app.ini` 檔案中添加一些配置
|
||||
- 重新啟動你的 Gitea 實例
|
||||
|
||||
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](../administration/customizing-gitea.md) page.
|
||||
這支援整個檔案的渲染。如果你想在 markdown 中渲染程式碼區塊，你需要使用 JavaScript。請參閱 [自訂 Gitea](../administration/customizing-gitea.md) 頁面上的一些範例。
|
||||
|
||||
## 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 映像檔，你的 `Dockerfile` 應該包含如下內容：
|
||||
|
||||
```docker
|
||||
FROM docker.gitea.com/gitea:@dockerVersion@
|
||||
@@ -30,22 +29,22 @@ 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
|
||||
# install any other package you need for your external renderers
|
||||
# 安裝任何其他你需要的外部渲染器套件
|
||||
|
||||
RUN pipx install jupyter docutils --include-deps --global
|
||||
# add above any other python package you may need to install
|
||||
# 添加任何其他你可能需要安裝的 Python 套件
|
||||
```
|
||||
|
||||
## `app.ini` file configuration
|
||||
## `app.ini` 檔案配置
|
||||
|
||||
add one `[markup.XXXXX]` section per external renderer on your custom `app.ini`:
|
||||
在你的自訂 `app.ini` 中為每個外部渲染器添加一個 `[markup.XXXXX]` 部分：
|
||||
|
||||
```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]
|
||||
@@ -61,13 +60,12 @@ 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/).
|
||||
如果你的外部標記依賴於生成的 HTML 元素上的額外類和屬性，你可能需要啟用自訂的清理策略。Gitea 使用 [`bluemonday`](https://godoc.org/github.com/microcosm-cc/bluemonday) 套件作為我們的 HTML 清理器。下面的範例可以用來支援來自 [`pandoc`](https://pandoc.org/) 的伺服器端 [KaTeX](https://katex.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>
|
||||
; Pandoc 將 TeX 段落渲染為帶有 "math" 類的 <span>，根據上下文可選地帶有 "inline" 或 "display" 類。
|
||||
; - 注意這與我們的 markdown 解析器內建的數學支援不同，後者使用 <code>
|
||||
ELEMENT = span
|
||||
ALLOW_ATTR = class
|
||||
REGEXP = ^\s*((math(\s+|$)|inline(\s+|$)|display(\s+|$)))+
|
||||
@@ -78,29 +76,28 @@ FILE_EXTENSIONS = .md,.markdown
|
||||
RENDER_COMMAND = pandoc -f markdown -t html --katex
|
||||
```
|
||||
|
||||
You must define `ELEMENT` and `ALLOW_ATTR` in each section.
|
||||
你必須在每個部分中定義 `ELEMENT` 和 `ALLOW_ATTR`。
|
||||
|
||||
To define multiple entries, add a unique alphanumeric suffix (e.g., `[markup.sanitizer.1]` and `[markup.sanitizer.something]`).
|
||||
要定義多個條目，請添加唯一的字母數字後綴（例如 `[markup.sanitizer.1]` 和 `[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]`.
|
||||
要僅對特定外部渲染器應用清理規則，它們必須使用渲染器名稱，例如 `[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.
|
||||
**注意**：如果規則定義在渲染器 ini 部分之上或名稱不匹配渲染器，則應用於每個渲染器。
|
||||
|
||||
Once your configuration changes have been made, restart Gitea to have changes take effect.
|
||||
一旦你的配置更改完成，重新啟動 Gitea 以使更改生效。
|
||||
|
||||
**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.
|
||||
**注意**：在 Gitea 1.12 之前，有一個單一的 `markup.sanitiser` 部分，具有為多個規則重新定義的鍵，但這種配置方法存在重大問題，因此需要通過多個部分進行配置。
|
||||
|
||||
### Example: HTML
|
||||
### 範例：HTML
|
||||
|
||||
Render HTML files directly:
|
||||
直接渲染 HTML 檔案：
|
||||
|
||||
```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]
|
||||
@@ -112,9 +109,9 @@ ELEMENT = a
|
||||
ALLOW_ATTR = class
|
||||
```
|
||||
|
||||
### Example: Office DOCX
|
||||
### 範例：Office DOCX
|
||||
|
||||
Display Office DOCX files with [`pandoc`](https://pandoc.org/):
|
||||
使用 [`pandoc`](https://pandoc.org/) 顯示 Office DOCX 檔案：
|
||||
|
||||
```ini
|
||||
[markup.docx]
|
||||
@@ -126,15 +123,15 @@ RENDER_COMMAND = "pandoc --from docx --to html --self-contained --template /path
|
||||
ALLOW_DATA_URI_IMAGES = true
|
||||
```
|
||||
|
||||
The template file has the following content:
|
||||
模板檔案具有以下內容：
|
||||
|
||||
```
|
||||
$body$
|
||||
```
|
||||
|
||||
### Example: Jupyter Notebook
|
||||
### 範例：Jupyter Notebook
|
||||
|
||||
Display Jupyter Notebook files with [`nbconvert`](https://github.com/jupyter/nbconvert):
|
||||
使用 [`nbconvert`](https://github.com/jupyter/nbconvert) 顯示 Jupyter Notebook 檔案：
|
||||
|
||||
```ini
|
||||
[markup.jupyter]
|
||||
@@ -146,11 +143,11 @@ RENDER_COMMAND = "jupyter-nbconvert --stdin --stdout --to html --template basic"
|
||||
ALLOW_DATA_URI_IMAGES = true
|
||||
```
|
||||
|
||||
## Customizing CSS
|
||||
## 自訂 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.
|
||||
外部渲染器在 .ini 中以 `[markup.XXXXX]` 格式指定，外部渲染器提供的 HTML 將包裹在帶有 `markup` 和 `XXXXX` 類的 `<div>` 中。`markup` 類提供了開箱即用的樣式（如果 `XXXXX` 是 `markdown`，則 `markdown` 也提供樣式）。否則，你可以使用這些類來專門針對渲染的 HTML 內容。
|
||||
|
||||
And so you could write some CSS:
|
||||
因此，你可以寫一些 CSS：
|
||||
|
||||
```css
|
||||
.markup.XXXXX html {
|
||||
@@ -177,7 +174,7 @@ And so you could write some CSS:
|
||||
}
|
||||
```
|
||||
|
||||
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`:
|
||||
將你的樣式表添加到自訂目錄，例如 `custom/public/assets/css/my-style-XXXXX.css`，並使用自訂標頭檔案 `custom/templates/custom/header.tmpl` 導入它：
|
||||
|
||||
```html
|
||||
<link rel="stylesheet" href="{{AppSubUrl}}/assets/css/my-style-XXXXX.css" />
|
||||
|
||||
Reference in New Issue
Block a user