From 49fb041ca04ee307923d549bbd96d96739e6e86f Mon Sep 17 00:00:00 2001
From: gryf <git@vimja.com>
Date: Wed, 6 Jul 2022 16:51:49 +0200
Subject: [PATCH] Documented configuration to get syntax highlight.

Basically all the configuration would contain two things - enabling
external renderer (rst2htmlbody) and allowance to use class for code
blocks.
---
 README.rst | 60 ++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 54 insertions(+), 6 deletions(-)

diff --git a/README.rst b/README.rst
index ffbe5ac..4e1d2ff 100644
--- a/README.rst
+++ b/README.rst
@@ -8,11 +8,11 @@ files.
 Installation
 ------------
 
-Before starting deployment of Gitea using docker or docker-compose, you'll
-need to create an altered image which would contain `docutils`_ python package.
-There is a simple Dockerfile attached, which can be adjusted to your needs
-(i.e. it might be needed to pin to stable version of gitea), than let's assume,
-that we tag the image with ``:rst``:
+Before starting deployment of Gitea using docker or docker-compose, you'll need
+to create an altered image which would contain `docutils`_ and `pygments`_
+python packages. There is a simple Dockerfile attached, which can be adjusted
+to your needs (i.e. it might be needed to pin to stable version of gitea), than
+let's assume, that we tag the image with ``:rst``:
 
 .. code:: shell
 
@@ -34,13 +34,59 @@ configuration. Stop the container, and alter file
    RENDER_COMMAND = "rst2htmlbody"
    IS_INPUT_FILE = false
 
+(see also section below)
 
-And that's it!
+And that's it! You can run your gitea instance again and enjoy html generated
+preview for reStructuredText.
 
 Unfortunately, you'll need to repeat those steps every time you'd like to
 update gitea.
 
 
+Syntax highlighting
+-------------------
+
+Gitea already have syntax highlighting support for markdown files, which uses
+`chroma`_ library which, as description says is heavily based on `pygments`_,
+which is pretty convenient, since it shares most of the mechanisms and ideas,
+including naming convention for the language elements inside ``code`` block. In
+other words, it seem to be super easy to adopt this little program to include
+also syntax highlighting, instead of generating (i.e. by using ``pygmentize``
+commandline tool) and adding separate CSS file as another step.
+
+The only thing which is needed to include is the ``class`` attribute for HTML
+element for ``code`` tag. To achieve that it's just a matter of additional
+entry in ``app.ini``, and that can be done together with altering ``app.ini``
+from previous section:
+
+.. code:: ini
+
+   [markup.sanitizer.restructuredtext.1]
+   ELEMENT = code
+   ALLOW_ATTR = class
+
+And that should be enough for having colored syntax highlighting.
+
+
+Testing
+-------
+
+You don't need to run docker-compose for running container based on the image,
+for testing purposes you could just run:
+
+.. code:: shell
+
+   $ docker build -t gitea:rst -f Dockerfile .
+   $ docker run --name gitea-test -p 3000:3000 -p 3022:22 -v ${PWD}/data:/data gitea:rst
+
+Adjust the settings in a browser, wait for them to propagate, than ``ctrl-c``
+to stop container, change the ``app.ini`` and start it again with:
+
+.. code:: shell
+
+   $ docker start gitea-test
+
+
 License
 -------
 
@@ -51,3 +97,5 @@ full license text.
 .. _docutils: https://docutils.sourceforge.io
 .. _gitea: https://gitea.io
 .. _same as documented: https://docs.gitea.io/en-us/install-with-docker/
+.. _chroma: https://github.com/alecthomas/chroma
+.. _pygments: http://pygments.org