blog/content/posts/using-asciidoc-with-gitea.adoc
2019-02-15 02:35:40 +01:00

112 lines
4.2 KiB
Plaintext

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