search

etiennebacher / altdoc

Alternative to pkgdown to document R packages
https://altdoc.etiennebacher.com
Other
67 stars 9 forks source link

[Quarto] Why requires `README.qmd`? #292

Closed eitsupi closed 1 month ago

eitsupi commented 1 month ago

I am wondering if it is possible to skip rendering if there is already README.md. pkgdown does not render the README, and I do not want to be forced to render it here.

pkgdown says rendering README is the responsibility of the user.

etiennebacher commented 1 month ago

I would need to look again in the internals but I think a quarto website requires index.qmd to be a qmd file. Or did you mean that we should convert README.md to index.qmd?

This was brought up before in #280 but I've never deployed a quarto website so @vincentarelbundock will know better.

vincentarelbundock commented 1 month ago

Yes, I believe that is the correct reason. I suppose we could copy .md to a .qmd, but that would be processed again by Quarto, which may lead to unexpected things (or not).

eitsupi commented 1 month ago

Thanks for the response. I am convinced that the simplest approach here is to automatically generate index.md file with the following content and include the contents of README.md in the index.md (as I wrote https://github.com/quarto-dev/quarto-cli/issues/1615#issuecomment-1220711273).

{{< include README.md >}}
eitsupi commented 1 month ago

I was going to fix this, but then I realized that altdoc tries to render the README for Rmd as well as qmd. Why did you choose this behavior as opposed to pkgdown?

My personal opinion is that READMEs are not rendered on CRAN so forcing them to be rendered when building a website seems like overkill.