mirror of
https://github.com/gryf/gitea-rest-renderer.git
synced 2025-12-17 03:20:27 +01:00
gryf
49fb041ca0
Basically all the configuration would contain two things - enabling external renderer (rst2htmlbody) and allowance to use class for code blocks.
102 lines
3.1 KiB
ReStructuredText
102 lines
3.1 KiB
ReStructuredText
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
|