wish: document external renderers support on website

[juanpablo-santos]

• Gitea version (or commit ref): 1.4.0
• Git version: 2.10.0
• Operating system: Official docker image
• Database (use [x]):
  • PostgreSQL
  • [X ] MySQL
  • MSSQL
  • SQLite
• Can you reproduce the bug at https://try.gitea.io:
  • Yes (provide example URL)
  • No
  • Not relevant
• Log gist:

Description

It would be nice if gitea could provide highlighting for Jupyter (ipython) notebooks (that is, .ipynb files), like f.ex., in https://gist.github.com/arogozhnikov/930f5663a63014e773d9

thx

[juanpablo-santos]

ftr, github seems to perform an ipynb -> static html conversion: https://help.github.com/articles/working-with-jupyter-notebook-files-on-github/

[juanpablo-santos]

Hi,

seems that Gitea currently supports external renderers from way back, although it isn't documented except on PRs #2570, #2877 and a few others; so I'm switching this request into a documentation request on the website, ( f.ex., External renderers support, probably under Advanced section).

In any case, I'm posting here required configuration for Jupyter (ipython) notebooks, asciidoctor and restructuredtext, as it might be useful for others; it's just matter of

• installing external renderers
• add configuration to your app.ini file
• restart your gitea instance

1.- Installing external renderers
In order for these sections to take effect, several external packages must be installed to get the external renderers going. If you're using a Docker image, your Dockerfile should contain something along this lines:

FROM gitea/gitea:1.5.0
[...]

COPY custom/app.ini /data/gitea/conf/app.ini
[...]

RUN apk --no-cache add asciidoctor freetype freetype-dev gcc g++ libpng python-dev py-pip python3-dev py3-pip
# install any other package you need for your external renderers

RUN pip3 install --upgrade pip
RUN pip3 install -U setuptools
RUN pip3 install jupyter matplotlib docutils 
# add above any other python package you may need to install

2.- app.ini file configuration

add one [markup.XXXXX] section per external renderer on your custom app.ini:

[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.jupyter]
ENABLED = true
FILE_EXTENSIONS = .ipynb
RENDER_COMMAND = "jupyter nbconvert --stdout --to html --template basic "
IS_INPUT_FILE = true

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

3.- restart your gitea instance
profit!

[lunny]

@juanpablo-santos could you send a PR to add these to the document.

[juanpablo-santos]

@lunny, #5387 should do it. Please let me know if anything else is needed.

thx!