4.1 KiB
title: "Using AsciiDoc(tor) with Gitea" description: "How to add AsciiDoc support to Gitea." date: 2019-01-26T13:03:36+01:00 draft: false tags: - AsciiDoc - Gitea ---
In this blogpost I describe what I did to get AsciiDoc support into Gitea. If you want more than syntax highlighting and basic formatting, Gitea has to be patched unfortunately(this issue has already been reported). But I think most people will only need to edit 1 configuration file and are done.
Asciidoctor or AsciiDoc?
Asciidoctor has inbuilt support for highlight.js, the solution Gitea uses and is therefore the best choice in most scenarios. If you can’t or don’t want to use it you can use AsciiDoc.
Add the following section to conf/app.ini
in your Gitea path. The change
causes .adoc
files to be rendered with asciidoctor.
ENABLED = true
; List of file extensions that should be rendered by an external command
FILE_EXTENSIONS = .adoc,.asciidoc
; External command to render all matching extensions
RENDER_COMMAND = "asciidoctor --backend=html5 --no-header-footer --attribute source-highlighter=highlightjs --out-file=- -"
; Don't pass the file on STDIN, pass the filename as argument instead.
If you want to use asciidoc instead the command would be:
asciidoc --backend=xhtml11 --no-header-footer --attribute
source-highlighter=highlight --out-file=- -
. I would choose the xhtml11
backend because it is the only one that encloses code snippets with <code>
tags. Instead of
highlight you can
use source-highlight or
Pygments.
If you use asciidoctor and don’t need tables or other fancy stuff you’re now done! If you use asciidoc, you’ll have to patch Gitea to get syntax highlighting.
Patching Gitea
The sanitizer strips almost all attributes from HTML-tags, as a security precaution. I’ve added exceptions for:
-
class
attributes on all the tags Asciidoctor introduces, -
Numerous attributes on
table
tags, -
align
andvalign
ontd
tags, -
style
attributes onspan
tags, but only if they contain nothing more than color and font definitions.
If you use Asciidoctor with highlight.js output, you don’t need to allow style
attributes, if you don’t use tables you can omit the lines that deal with them
and the class
exception is only useful if you add custom CSS to use them.
Apply the patch with patch -p1 < gitea_relax-sanitizer.patch
.
diff --git a/modules/markup/sanitizer.go b/modules/markup/sanitizer.go
index fd6f90b2a..ae11811b6 100644
--- a/modules/markup/sanitizer.go
+++ b/modules/markup/sanitizer.go
@@ -41,5 +41,16 @@ func NewSanitizer() {
// Allow keyword markup
sanitizer.policy.AllowAttrs("class").Matching(regexp.MustCompile(`^` + keywordClass + `$`)).OnElements("span")
+
+ // Allow style on span tags
+ sanitizer.policy.AllowAttrs("style").Matching(regexp.MustCompile(`^(background-)?color:[^;]+(; ?font[^;]+)?;?$`)).OnElements("span")
+
+ // Allow class attribute
+ sanitizer.policy.AllowAttrs("class").OnElements("code", "pre", "span", "div", "p", "table", "td")
+
+ // Allow table attributes
+ sanitizer.policy.AllowAttrs("width", "frame", "rules", "cellspacing", "cellpadding").OnElements("table")
+ sanitizer.policy.AllowAttrs("width").OnElements("col")
+ sanitizer.policy.AllowAttrs("align", "valign").OnElements("td")
})
}
Tables without borders
I used tables without borders in a manpage I wrote for the list of options. Gitea insist on drawing borders around them, so I had to create a custom CSS snippet.
In your Gitea directory, create custom/templates/custom/header.tmpl
.
/* Additions for asciidoc */
.markdown:not(code) table.frame-none
{
border: 0 !important;
}
.markdown:not(code) table.grid-none *
{
border: 0 !important;
}
Updates
-
2019-11-14: Updated Gitea patch for 1.10.0.