Publishing to github pages with quarto

[njtierney]

Description

Hi there!

I'm trying to create a minimal reprex on my issues with publishing to quarto via gh pages.

My goal is that I want the book to be rebuilt upon pushes to main. I don't want to push HTML content onto the site. I don't want to have to run commands from the command line every time I want to publish to github (although it is cool that that works!)

I see that this is an issue which has been discussed, but I can't actually seem to find an answer to my problem.

My process - following on from https://quarto.org/docs/publishing/github-pages.html#publish-command

1. via rstudio, create a quarto book, "quarto-gh-pages"
2. create github repo, "quarto-gh-pages"
3. push content onto repo - first commit here
4. run quarto publish gh-pages in the command line of the repo:

This then produces a book as a website! Woo!

But my goal is that I want the book to be rebuilt upon pushes to main. I don't want to push HTML content onto the site.

When I push another change to the repo, no new build. See this commit

Follow instructions from quarto website:

Once you’ve completed a local publish, add a publish.yml GitHub Action to your project by creating this YAML file and saving it to .github/workflows/publish.yml:

So I add a publish.yml file

This then fails:

Error in loadNamespace(x) : there is no package called ‘rmarkdown’

OK, so I need to have R installed and R packages available now? Perhaps add renv?

Following instructions from: https://rstudio.github.io/renv/articles/ci.html

I add R and renv in this commit

Error due to no lockfile

Error: This project does not contain a lockfile.

OK, add a lockfile

But TeX isn't installed:

No TeX installation was detected.
Please run 'quarto install tinytex' to install TinyTex.
If you prefer, you may install TexLive or another TeX distribution.

Alright, so, add tinytex

This worked!

This seems like a fair number of hoops to need to run through, I'm wondering if there's a way to automate a few of these steps? Am I missing something? It seems like I'm probably missing something, but I'd really appreciate some guidance here, as I feel like there's some great opportunities to make this as easy as possible.

[mcanouil]

As you noticed, we are aware of the "publish to GitHub Pages" documentation issue which is a bit outdated and the fact that current default error about missing _publish.yml this is actually only for Netlify and means "you need to run quarto publish gh-pages locally first.

If you don't use PDF as output, there is no need for TinyTex, if you don't have computations you don't need either Jupyter or R.
It's not really feasible to guess any user dependencies to be set in GitHub Actions, that's up to the user unfortunately.

Note that you have several examples and documentation of GitHub Actions workflows at https://github.com/quarto-dev/quarto-actions.
This link is provided in Continuous integration section about GitHub Actions: https://quarto.org/docs/publishing/ci.html#github-actions

[njtierney]

Thanks for the quick response!

And I should also preface this by saying firstly thank you everyone for writing such a useful piece of software, thanks!

As you noticed, we are aware of the "publish to GitHub Pages" documentation issue which is a bit outdated and the fact that current default error about missing _publish.yml this is actually only for Netlify and means "you need to run quarto publish gh-pages locally first.

If I understand correctly, quarto publish gh-pages only needs to be run when using netlify? So this section: https://quarto.org/docs/publishing/github-pages.html#publish-action is inaccurate now?

What happens if the user doesn't use quarto publish gh-pages? Can they still use a github action and it will publish to github pages for them? Or is it that the user needs to create a gh-pages branch, and that quarto command does that?

If you don't use PDF as output, there is no need for TinyTex, if you don't have computations you don't need either Jupyter or R.
It's not really feasible to guess any user dependencies to be set in GitHub Actions, that's up to the user unfortunately.

Yup, that's totally fair!

[mcanouil]

Netlify is another hosting services which requires the _publish.yml.

GitHub Pages does not need that.
But currently, if you set your GitHub workflow without first publishing locally, the workflow will fail showing an error involving _publish.yml. This is a currently wrong error message.
When you use quarto publish gh-pages you are publishing to GitHub Pages, nowhere else.

As I said and as stated in the documentation (that part is correct), no matter if you want to use GitHub Action or not: you first need to use quarto publish gh-pages locally. It will do everything except setting GitHub action workflow.

[johann-wagner]

Not too sure if this helps, but I found this video useful:
Publish a Quarto project using GitHub Pages+GitHub Actions in 6 minutes (no need to render locally!)