pub-solar/forgejo
5
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

Update Asciidoc markup example with safe defaults (#24920)

Browse source 
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.
This commit is contained in:
Mike Rochefort 2023-05-24 21:24:05 -04:00 committed by GitHub
parent 69e73fdcff
commit d7e669c371
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 2 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/content/doc/administration/config-cheat-sheet.en-us.md
View file

@ -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
```

2
docs/content/doc/administration/config-cheat-sheet.zh-cn.md
View file

@ -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
```