diff options
| author | Mike Rochefort <mroche@omenos.dev> | 2023-05-24 21:24:05 -0400 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2023-05-25 01:24:05 +0000 |
| commit | d7e669c3719f74340096c212a1228bb11c028652 (patch) | |
| tree | aa7d4624fb5c81ad72a3821daadab8fe5038c2b2 /docs | |
| parent | 69e73fdcff0e7fe9bd708c0a8dd70fdcb2de3135 (diff) | |
| download | gitea-d7e669c3719f74340096c212a1228bb11c028652.tar.gz gitea-d7e669c3719f74340096c212a1228bb11c028652.zip | |
Update Asciidoc markup example with safe defaults (#24920)
The cheat sheet uses the `asciidoc` markup language to demonstrate how
to set up third party markup renderers. The current example has the
following issues:
- It promotes a legacy tool that does not handle modern AsciiDoc
specifications
- It does not account for embedded preview renders
- It has no safety restrictions
By switching to `asciidoctor`, uses are suggested to utilize de
facto/standard tooling for AsciiDoc.
The `--embedded` parameter will strip out HTML tags that contain the
document (such as `<html></html>`) which aren't necessary for the
render, and actually end up as text in the document if left in.
The `--safe-mode` parameter (of which there are several profiles)
imposes [certain
policies](https://docs.asciidoctor.org/asciidoctor/latest/safe-modes/)
on the files it ingests and what the resulting output looks like. GitHub
itself uses the `secure` profile (the highest), which can be a good
starting point for those who are uncertain of what to do. By default, if
no mode is specified when `asciidoctor` runs it defaults to `unsafe`,
i.e. no safety guidelines at all.
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/content/doc/administration/config-cheat-sheet.en-us.md | 2 | ||||
| -rw-r--r-- | docs/content/doc/administration/config-cheat-sheet.zh-cn.md | 2 |
2 files changed, 2 insertions, 2 deletions
diff --git a/docs/content/doc/administration/config-cheat-sheet.en-us.md b/docs/content/doc/administration/config-cheat-sheet.en-us.md index 18321ee883..e7e482fc79 100644 --- a/docs/content/doc/administration/config-cheat-sheet.en-us.md +++ b/docs/content/doc/administration/config-cheat-sheet.en-us.md @@ -1118,7 +1118,7 @@ Gitea can support Markup using external tools. The example below will add a mark ENABLED = true NEED_POSTPROCESS = true FILE_EXTENSIONS = .adoc,.asciidoc -RENDER_COMMAND = "asciidoc --out-file=- -" +RENDER_COMMAND = "asciidoctor --embedded --safe-mode=secure --out-file=- -" IS_INPUT_FILE = false ``` diff --git a/docs/content/doc/administration/config-cheat-sheet.zh-cn.md b/docs/content/doc/administration/config-cheat-sheet.zh-cn.md index c672b61598..ba28b98123 100644 --- a/docs/content/doc/administration/config-cheat-sheet.zh-cn.md +++ b/docs/content/doc/administration/config-cheat-sheet.zh-cn.md @@ -337,7 +337,7 @@ test01.xls: application/vnd.ms-excel; charset=binary ENABLED = false NEED_POSTPROCESS = true FILE_EXTENSIONS = .adoc,.asciidoc -RENDER_COMMAND = "asciidoc --out-file=- -" +RENDER_COMMAND = "asciidoctor --embedded --safe-mode=secure --out-file=- -" IS_INPUT_FILE = false ``` |