blog/content/posts/using-asciidoc-with-gitea.adoc

---
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 `<code>`
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: