External renderers and included files #3065

@lunny commented on GitHub (Mar 18, 2019):

Could you have a similiar config with below?

[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

@lunny commented on GitHub (Mar 18, 2019): Could you have a similiar config with below? ```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 ```

GiteaMirror commented

@gautaz commented on GitHub (Mar 18, 2019):

Could you have a similiar config with below?

[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

This is in fact my current configuration (taken as is from here).

@gautaz commented on GitHub (Mar 18, 2019): > Could you have a similiar config with below? > > ```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 > ``` This is in fact my current configuration (taken as is from [here](https://docs.gitea.io/en-us/external-renderers/)).

GiteaMirror commented

@gautaz commented on GitHub (Apr 2, 2019):

@lunny Is there a way to pass asciidoctor a path to the project sources by using the --base-dir option?

@gautaz commented on GitHub (Apr 2, 2019): @lunny Is there a way to pass `asciidoctor` a path to the project sources by using the [`--base-dir` option](https://asciidoctor.org/man/asciidoctor/#security-settings)?

GiteaMirror commented

2025-11-02 04:59:29 -06:00

@stale[bot] commented on GitHub (Jun 7, 2019):

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs during the next 2 weeks. Thank you for your contributions.

@stale[bot] commented on GitHub (Jun 7, 2019): This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs during the next 2 weeks. Thank you for your contributions.

GiteaMirror commented

@gautaz commented on GitHub (Jun 7, 2019):

Sorry to insist but the current way to integrate external renderers by using the standard input to feed them will not work for any renderer using other files from the project (for instance in case of document sources including project files).

It seems to me that Asciidoctor is just an example among others.

As Gitea is a collaborative project, I also totally understand that this issue cannot be resolved for now unless someone skilled enough has the time to handle it but I do not understand how closing automatically the issue will help.

Am I the only one thinking that the current external renderer integration method cannot cover all use cases?
Perhaps an agreement on this point is necessary as a preamble to adding an item in the Gitea roadmap?

@gautaz commented on GitHub (Jun 7, 2019): Sorry to insist but the current way to integrate external renderers by using the standard input to feed them will not work for any renderer using other files from the project (for instance in case of document sources including project files). It seems to me that Asciidoctor is just an example among others. As Gitea is a collaborative project, I also totally understand that this issue cannot be resolved for now unless someone skilled enough has the time to handle it but I do not understand how closing automatically the issue will help. Am I the only one thinking that the current external renderer integration method cannot cover all use cases? Perhaps an agreement on this point is necessary as a preamble to adding an item in the Gitea roadmap?

GiteaMirror commented

2025-11-02 04:59:29 -06:00

@zeripath commented on GitHub (Jun 7, 2019):

Why don't you write a script that will set up the environment correctly for ascidoctor?

You can send the stdin to a temporary file run ascidoctor on that or deal with the input file and then cat the output back out.

@zeripath commented on GitHub (Jun 7, 2019): Why don't you write a script that will set up the environment correctly for ascidoctor? You can send the stdin to a temporary file run ascidoctor on that or deal with the input file and then cat the output back out.

GiteaMirror commented

2025-11-02 04:59:29 -06:00

@gautaz commented on GitHub (Jun 7, 2019):

@zeripath Are you saying that this script would be executed instead of asciidoctor and will hand the missing elements over to asciidoctor once it gathered all the missing pieces?
How is this script supposed to access the other files of the git repository where the document source is located? This script will get the same data than asciidoctor, that is a standard input with the content of the document source to process but no information about where to get the other parts of the git repository.

@gautaz commented on GitHub (Jun 7, 2019): @zeripath Are you saying that this script would be executed instead of asciidoctor and will hand the missing elements over to asciidoctor once it gathered all the missing pieces? How is this script supposed to access the other files of the git repository where the document source is located? This script will get the same data than asciidoctor, that is a standard input with the content of the document source to process but no information about where to get the other parts of the git repository.

GiteaMirror commented

@stale[bot] commented on GitHub (Aug 7, 2019):

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs during the next 2 weeks. Thank you for your contributions.

@stale[bot] commented on GitHub (Aug 7, 2019): This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs during the next 2 weeks. Thank you for your contributions.

GiteaMirror commented

@Jim-Bar commented on GitHub (Sep 26, 2019):

Interested as well in a solution to this problem. Including other files doesn't work with e.g. AsciiDoc which is unfortunate because it's a great feature. As such, our documentation cannot be properly viewed from Gitea.

@gautaz Thanks for opening this issue ;)

@Jim-Bar commented on GitHub (Sep 26, 2019): Interested as well in a solution to this problem. Including other files doesn't work with e.g. AsciiDoc which is unfortunate because it's a great feature. As such, our documentation cannot be properly viewed from Gitea. @gautaz Thanks for opening this issue ;)

GiteaMirror commented

@shomodj commented on GitHub (May 1, 2021):

Also interested in solution for this...

Can we fund this?

@shomodj commented on GitHub (May 1, 2021): Also interested in solution for this... Can we fund this?

GiteaMirror commented

@raylee commented on GitHub (Mar 2, 2022):

I have the same issue, but for a different file format. If the external renderer could be passed the path to the git repository as a substitution or environment variable in RENDER_COMMAND, the rest could be handled outside of Gitea.

Something like

RENDER_COMMAND = "myFormatRenderer -g $GITEA_REPO_ROOT ... -o -"

would work fine. (Or if the user is running on Windows, they could use the %VAR% form for the command.)

The external renderer would then be able to check out the necessary supporting files which are needed.

@raylee commented on GitHub (Mar 2, 2022): I have the same issue, but for a different file format. If the external renderer could be passed the path to the git repository as a substitution or environment variable in RENDER_COMMAND, the rest could be handled outside of Gitea. Something like ``` RENDER_COMMAND = "myFormatRenderer -g $GITEA_REPO_ROOT ... -o -" ``` would work fine. (Or if the user is running on Windows, they could use the %VAR% form for the command.) The external renderer would then be able to check out the necessary supporting files which are needed.

GiteaMirror commented

@lunny commented on GitHub (Mar 3, 2022):

OK. So I think the requirement is Expose related renderer context information as variables for the RENDER_COMMAND.

@lunny commented on GitHub (Mar 3, 2022): OK. So I think the requirement is `Expose related renderer context information as variables for the RENDER_COMMAND`.

GiteaMirror commented

@lunny commented on GitHub (Mar 3, 2022):

Let's make a sample. Assume we have a git directory in a repository like this.

- index.html
- images/logo.png

Then I want to display the logo image in the HTML file if I enabled the third-party renderer for .html extensions.

Is that you want?

@lunny commented on GitHub (Mar 3, 2022): Let's make a sample. Assume we have a git directory in a repository like this. ``` - index.html - images/logo.png ``` Then I want to display the logo image in the HTML file if I enabled the third-party renderer for `.html` extensions. Is that you want?

GiteaMirror commented

@raylee commented on GitHub (Mar 3, 2022):

For my use case, the renderer needs to get at the git history to show summaries of what changed. So while this bug itself is about related files, I need to rummage around the git history. Hence my request for an environment variable (or command substitution) of a path to the repo.

This would address both my use case (looking back in time), as well as this bug's request (finding supporting files).

@raylee commented on GitHub (Mar 3, 2022): For my use case, the renderer needs to get at the git history to show summaries of what changed. So while this bug itself is about related files, I need to rummage around the git history. Hence my request for an environment variable (or command substitution) of a path to the repo. This would address both my use case (looking back in time), as well as this bug's request (finding supporting files).

GiteaMirror commented

@johnnybubonic commented on GitHub (Mar 6, 2022):

Just hit this one myself. :/ Bummer.

How is the render executed? Is a checkout performed or does it pull the browser-requested file specifically from git? If the former, this should be fairly easy - just provide a RENDER_CMD directive in markup.* of app.ini that provides the directory of the cloned repository as an env var. A couple wrapper scripts or programs and rendering can be performed however desired. I suspect this is not how it's done, however, as that'd be a nightmare to implement for multiple requests and refs in parallel.

If the latter, however... it's not really possible, as gitea itself would need to be parser-aware of each markup language they wanted to support, which defeats the entire purpose of a "modular" system like it currently is designed to be.

So I'd personally probably classify this as WONTFIX because I suspect it's impossible.

For those needing a solution, however, how I've implemented this in the past is simply with a pre-commit hook that just renders to e.g. an HTML file (I'm a heavy user of Asciidoctor). Unfortunate that it then needs to be on every machine though. There are some proposed solutions (including setting DISABLE_GIT_HOOKS to false).
I find that https://github.com/gabyx/Githooks is probably the most elegant approach.

@johnnybubonic commented on GitHub (Mar 6, 2022): Just hit this one myself. :/ Bummer. How is the render executed? Is a checkout performed or does it pull the browser-requested file specifically from git? If the former, this should be fairly easy - just provide a RENDER_CMD directive in `markup.*` of `app.ini` that provides the directory of the cloned repository as an env var. A couple wrapper scripts or programs and rendering can be performed however desired. I suspect this is not how it's done, however, as that'd be a nightmare to implement for multiple requests and refs in parallel. If the latter, however... it's not really possible, as gitea itself would need to be parser-aware of each markup language they wanted to support, which defeats the entire purpose of a "modular" system like it currently is designed to be. So I'd personally probably classify this as WONTFIX because I suspect it's impossible. For those needing a solution, however, how I've implemented this in the past is simply with a pre-commit hook that just renders to e.g. an HTML file (I'm a heavy user of Asciidoctor). Unfortunate that it then needs to be on every machine though. There are [some](https://www.viget.com/articles/two-ways-to-share-git-hooks-with-your-team/) [proposed](https://github.com/gabyx/Githooks) solutions (including [setting](https://docs.gitea.io/en-us/config-cheat-sheet/#security-security) `DISABLE_GIT_HOOKS` to `false`). I find that https://github.com/gabyx/Githooks is probably the most elegant approach.

GiteaMirror commented

@lunny commented on GitHub (Mar 6, 2022):

Since you could do that in markdown with ![Alt text](relative_path/img.jpg) to render an image, I don't think this is not impossible for images. We just need to parse image elements and replace the relative link to Gitea's file raw link.
For CSS, Javascript, we need to assess whether there are some security problem.

@lunny commented on GitHub (Mar 6, 2022): Since you could do that in markdown with `![Alt text](relative_path/img.jpg)` to render an image, I don't think this is not impossible for images. We just need to parse image elements and replace the relative link to Gitea's file raw link. For CSS, Javascript, we need to assess whether there are some security problem.

GiteaMirror commented