• Enable Asciidoctor Rendering with Gitea

    , Romain Manni-Bucau, 2022-12-02, 2 min and 5 sec read

    Gitea is a great base for on premise dev factories. Combined with Drone it enables to have a fully self-hosted source/project management and CI/CD solution.

    However, by default it does not support very well Asciidoc file - it does not render it.

    Enable Asciidoctor rendering

    To solve that the idea is to install asciidoctor - the doc mention asciidoc but asciidoctor is more reliable these days, then simply configure the app.ini of Gitea to use it to render .adoc files. Since I’m using a local Kubernetes cluster, here is how I built a custom image to run Gitea:

    FROM docker.io/gitea/gitea:1.17.2 (1)

RUN apk add --no-cache asciidoctor && \ (2)
    rm -vrf /var/cache/apk/*
    1 Start the standard gitea image,
    2 Add asciidoctor executable and clean up the installation cache.

    Build the image (nothing specific there): docker build -t mygitea:latest ..

    personally I tend to tag the image using the pattern ${gitea.version}.${build.version}.

    Then, in my app.ini add:

    [markup.asciidoc]
ENABLED=true
FILE_EXTENSIONS=.adoc (1)
IS_INPUT_FILE=false (2)
RENDER_COMMAND=asciidoctor -S unsafe -s --attribute showtitle=true - (3)
    1 You can add other extensions seprating them by commas, for example .adoc,.asciidoc,.asciidoctor,
    2 Just pass the file content as a pipe (through stdin),
    3 Command is explained in next part.

    And now you can run gitea using mygitea image and the .adoc files can be browsed in a proper way.

    note that this rendering uses stdin to pass the content of the file, Gitea does not support file rendering respecting the layout (file rendering uses a temp file in a "sandbox" folder) so it means you can loose some build time features like includes.

    asciidoctor command

    As you see, you can use the command you want to render the .adoc file.

    Here we used asciidoctor -S unsafe -s --attribute showtitle=true -, let’s break it down:

    • -S unsafe: unsafe rendering enables more features, since the input is already sandboxed it is mainly about external references, icons, source highlightment…​ See safe modes for details.

    • -s: no header/footer option, enables to just get the content rendering and not a full html document (no head/body tags),

    • --attribute showtitle=true: -s disables h1 titles so we loose some data, adding this attribute enables to get the best of both worlds, ie just a content rendering with titles,

    • -: request asciidoctor to render the stdin instead of expecting a file.

    From the same author:

    In the same category:

    Navigation