Skip to main content


Fix AsciiDoc Display in Gitea


After installing my own Gitea I looked for the support for the markups I use.Gitea has support for external markup renderers and the official doc lists configs for both reStructuredText and AsciiDoc:

[markup.asciidoc]
ENABLED = true
FILE_EXTENSIONS = .adoc,.asciidoc
RENDER_COMMAND = "asciidoctor --out-file=- -"
; Input is not a standard input but a file
IS_INPUT_FILE = false

[markup.restructuredtext]
ENABLED = true
FILE_EXTENSIONS = .rst
RENDER_COMMAND = rst2html.py
IS_INPUT_FILE = false

RST works perfectly but AsciiDoc has two visible problems:
Image/PhotoGlitch on the topImage/PhotoUseless timestamp on the bottom
Unfortunately it seems that the Asciidoctor CLI cannot produce html code that will be correctly rendered by Gitea so we need to use the Ruby interface.

require 'asciidoctor'

# Load the document in the embeddable mode
document = Asciidoctor.load STDIN.read

# Embeddable doesn't display the main header so render it manually
puts "<h1>#{document.doctitle}&lt;/h1>"

# Render HTML
puts document.convert

Now replace the asciidoctor call with our new script:

[markup.asciidoc]
ENABLED = true
FILE_EXTENSIONS = .adoc,.asciidoc
RENDER_COMMAND = "ruby /path/to/gitea-asciidoc.rb"
; Input is not a standard input but a file
IS_INPUT_FILE = false

and enjoy a non glitchy AsciiDoc render.
https://sandfox.me/ruby/gitea-asciidoc.html