gh-actions documentation issues

[cboettig]

Bug description

Thanks for the amazing work on quarto, it's been a fantastic resource for which we keep discovering new applications!

First, apologies if this is not actually the best repository to report issues with quarto documentation, but this is where the link "Report an Issue with this page" points on your documentation, https://quarto.org/docs/publishing/github-pages.html, so I figured I'd start here. Maybe those docs can point to a different issue tracker if that's preferred?

On that page, under publish action the docs read:

before configuring the publishing action, it’s important that you run quarto publish gh-pages locally, once. This will create the _publish.yml configuration required by the subsequent invocations of the GitHub Action. To do this, run the following from within your project:

I think this should be publish.yml without an underscore. The rest of the docs refer to it with no underscore. More importantly, I and colleagues frequently see a quarto error

ERROR: No _publish.yml file available (_publish.yml specifying a destination required for non-interactive publish)

when trying to publish with a GitHub Action. This is a confusing error, because the only mention of a _publish.yml file (with underscore) is the one above, which I am pretty sure is not what the error ERROR: No _publish.yml is referring to. It sounds like this is a top-level config file, similar to _quarto.yml, but I'm not sure because I cannot find documentation describing it. It is a bit of a weird error, because it is very explicit in saying that such a file is required for non-interactive publication and yet github repositories configured to do non-interactive publishing don't have such a file, so I am worried that the error message is both spurious and asserting a requirement that is (no longer?) a requirement? I believe this is related to quarto-dev/quarto-actions#50.

Thanks for considering!

Checklist

• Please include a minimal, fully reproducible example in a single .qmd file? Please provide the whole file rather than the snippet you believe is causing the issue.
• Please format your issue so it is easier for us to read the bug report.
• Please document the RStudio IDE version you're running (if applicable), by providing the value displayed in the "About RStudio" main menu dialog?
• Please document the operating system you're running. If on Linux, please provide the specific distribution.
• Please provide the output of quarto check so we know which version of quarto and its dependencies you're running.

[mcanouil]

I am quoting my old self from two weeks ago:

Indeed some of the documentation is obsolete.

For instance, the part about creating the gh-pages is no longer needed.
.gitignore is needed if you don’t want to pollute your main branch as quarto publish gh-pages will render the project, thus creating _site.
So, I would still recommend to add .quarto and _site to it.
Note, that if the website is rendered via CI to gh-pages you can omit it, since you won’t render on main.
To continue on GitHub Actions, the paragraph about _publish.yml seems off.
I use GHA since the beginning and I don’t know what that is beside, but it seems to be used for non interactive purposes (see screenshot). On the other hand, the GHA is indeed .github/workflows/publish.yml (https://github.com/quarto-dev/quarto-actions)
Finally, since the publish GHA relies on quarto publish gh-pages , I was expected for the GHA to just work, but Quarto is complaining about the missing _publish.yml while it does not if the gh-pages already exist in this case, but no trace anywhere of _publish.yml.
For now, I can’t tell why it’s required in CI but not elsewhere.
To note, I don’t think _publish.yml is needed at all for gh-pages or the error message is not really clear, because for gh-pages what’s really triggering the error seems to be the lack of an existing target (even if the target is defined in the command), not the last of a _publish.yml.

Below commands used to check this

quarto create project website gh-pages
cd gh-pages
quarto render
git init
gh repo create quarto-gh-pages2 --public
git remote add origin https://github.com/mcanouil/quarto-gh-pages2.git
echo "/_site/" > .gitignore
echo "/.quarto/" >> .gitignore
git add . .gitignore
git commit -m "chore: initial commit"
git push origin main
# Add publish GHA
# Trigger GHA -> fail

quarto publish gh-pages
git push origin :gh-pages
# Trigger GHA -> success

While from documentation