112 lines
4.2 KiB
Plaintext
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 >}}
|
|
----
|