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

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.

----
{{< highlight ini >}}[markup.asciidoc]
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.
IS_INPUT_FILE = false{{< / highlight >}}
----

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

----
{{< highlight diff >}}diff -ur a/modules/markup/sanitizer.go b/modules/markup/sanitizer.go
--- a/modules/markup/sanitizer.go   2019-01-26 16:04:56.014108339 +0100
+++ b/modules/markup/sanitizer.go   2019-01-26 16:03:21.776401012 +0100
@@ -38,6 +38,16 @@
 
        // Custom URL-Schemes
        sanitizer.policy.AllowURLSchemes(setting.Markdown.CustomURLSchemes...)
+       // 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")
    })
 }{{< / highlight >}}
----

== 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`.

----
{{< highlight css >}}<style>
    /* Additions for asciidoc */
    .markdown:not(code) table.frame-none
    {
        border: 0 !important;
    }
    .markdown:not(code) table.grid-none *
    {
        border: 0 !important;
    }
</style>{{< / highlight >}}
----

== Comments

{{% mastodon-api-comments instance="soc.ialis.me" status_id="101483651770835303" %}}