Render README files with images in GitHub repo subfolders

[wurli]

Hi,

I'm having some trouble with this and any help would be appreciated. Say I have a GitHub repo with a subfolder first-post. Within the sub-folder I have a quarto file first-post/doc.qmd that looks like this:

---
title: "First post"
format: 
  gfm:
    output-file: README.md
---

Here's a plot:
```{r}
hist(rnorm(1000))
```

I have two issues:

1. Rendering the document in RStudio produces this error:

   ERROR: The filename, directory name, or volume label syntax is incorrect. (os error 123)
   

2. Despite the above error the document seems to render. However the output file contains the following line to indicate where the rendered histogram plot file lives:

   ![](doc_files/figure-gfm/unnamed-chunk-1-1.png)
   

GitHub would expect a 'full' filepath here when rendering the markdown file, i.e. it would expect first-post/doc_files/figure-gfm/unnamed-chunk-1-1.png, however I haven't been able to find any option that causes quarto/pandoc to render paths this way.

Any help much appreciated!

[cderv]

This is something that is indeed specific to Github Markdown when deployed and rendered to HTML through Github. Links are relative to the repository or absolute.

I believe Pandoc is supposed to support this now with the non standard extension rebase_relative_paths See doc https://pandoc.org/MANUAL.html#extension-rebase_relative_paths and discussion in issue (jgm/pandoc#3752)

However, it seems this extension does not work with Quarto.

---
title: "First post"
format: 
  gfm:
    output-file: README.md
    from: markdown+rebase_relative_paths
---

Here's a plot:

```{r}
hist(rnorm(1000))
```

Which gives me

First post
================

Here’s a plot:

``` r
hist(rnorm(1000))
```

![](C:\Users\chris\AppData\Local\Temp\quarto-session0499d54f\4593c2f2/test_files/figure-gfm/unnamed-chunk-1-1.png)

So an absolute because of where Quarto is rendering with pandoc (or something else...)

With knitr, there should be a way to do that already by using the base.url options (https://yihui.org/knitr/options/#package-options).
However, it does not work in Quarto - this is probably an unsupported option for now. I'll open an issue about that.

This is how you could do it with R Markdown.

---
title: "First post"
output: github_document
---

```{r}
knitr::opts_knit$set(base.url = "firstpost/")
```


Here's a plot:

```{r}
hist(rnorm(1000))
```

resulting in

First post
================

``` r
knitr::opts_knit$set(base.url = "firstpost/")
```

Here’s a plot:

``` r
hist(rnorm(1000))
```

![](firstpost/test_files/figure-gfm/unnamed-chunk-2-1.png)<!-- -->

which we want.

This should work in Quarto too, at least i would have expected. But the base.url knitr option is not supported.

I wonder if we should do that by default for Github document output - Lua is quite simple for that

Image = function(el)
  el.src = "firstpost/" .. el.src
  return el
end

Transforming that to an extension, and using some parameter would allow to tweak source url on all images parsed by Pandoc.
Maybe we can even derive the path of the file from the root based on Quarto information passed to Lua filter.

We could add to @quarto-ext maybe 🤔 Or just internalize in gfm output or at least provide a fix / workaround for rebase_relative_paths

Thanks a lot for your question, as you see it got me thinking 😅

[wurli]

Thanks very much, this is a great answer 😃

I think the Lua filter option is probably the simplest isn't it. It does seem like something that should have a baked-in option though (and perhaps it should be turned on by default if this behaviour is something of a red herring). I vaguely recall running into this issue with R Markdown in the past and I think I did exactly what you suggest, IMO it doesn't feel very elegant though.

I think for now I'll use the Lua filter option, but yes, it'd be great if this could be baked into Quarto 😸

Thanks again!