Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/gryf/gitea-rest-renderer

ReStructured Text renderer for Gitea
https://github.com/gryf/gitea-rest-renderer

gitea restructured-text

Last synced: about 2 months ago
JSON representation

ReStructured Text renderer for Gitea

Awesome Lists containing this project

README 

        
Restructured text renderer for Gitea

====================================



This is simple custom rst2html5 renderer for `Gitea`_ for reStructuredText

files.



Installation

------------



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



   $ docker build -t gitea:rst -f Dockerfile .



Procedure of running dockerized deployment is `same as documented`_ - of course

you'll need to change line with image to align newly created altered image.



Now, as you have it up and running, there is still a need for altering

configuration. Stop the container, and alter file

``path-to/gitea/conf/app.ini``, and add external renderer section:



.. code:: ini



   [markup.restructuredtext]

   ENABLED = true

   FILE_EXTENSIONS = .rst

   RENDER_COMMAND = "rst2htmlbody"

   IS_INPUT_FILE = false



(see also section below)



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

-------



This project is licensed under the MIT License. See the LICENSE file for the

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