--- 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 --- :source-highlighter: pygments In this blogpost I describe what I did to get AsciiDoc support into https://gitea.io/[Gitea]. If you want more than syntax highlighting and basic formatting, Gitea has to be patched unfortunately(this https://github.com/go-gitea/gitea/issues/4935[issue] has already been reported). But I think most people will only need to edit 1 configuration file and are done. == Asciidoctor or AsciiDoc? https://asciidoctor.org/[Asciidoctor] has inbuilt support for https://highlightjs.org/[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 http://asciidoc.org/[AsciiDoc]. Add the following section to `conf/app.ini` in your Gitea path. The change causes `.adoc` files to be rendered with asciidoctor. [source,ini] ---- 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 `

`
tags. Instead of
http://www.andre-simon.de/doku/highlight/en/highlight.html[highlight] you can
use http://www.gnu.org/software/src-highlite/[source-highlight] or
http://pygments.org/[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` and `valign` on `td` tags,
* `style` attributes on `span` 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`.

[source,diff]
----
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`.

[source,css]
----
    /* 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.

// Local Variables:
// no-ws-cleanup: t
// End: