Document how to setup custom domain on Github Pages when using `quarto publish gh-pages`

[cderv]

Discussed in #3249

^{Originally posted by jmgirard November 8, 2022}
I am hosting a Quarto website on Github Pages using the "docs" method. I have a custom domain and thus need to have a docs/CNAME file in my project. However, it seems that quarto is removing this file whenever I render via quarto render. Is there a way to tell quarto to keep this CNAME file? I tried the website: site-url option but that didn't seem to do it.

This is also from quarto-dev/quarto-actions#73

[cderv]

Proposed solution:

• Add the CNAME file in the root of Quarto project
• add it as an explicit resource in your _quarto.yml configuration:

resources:
  - CNAME

[cwickham]

Maybe this belongs in https://quarto.org/docs/publishing/github-pages.html#render-to-docs.

But perhaps this is actually an issue for all publishing methods (rendering to docs, quarto publish, and GitHub actions). The Overview mentions custom domains in its final paragraph, so perhaps this really needs to be its own section linked from there.

@cscheid or @cderv could one of you confirm if the proposed solution applies to all publishing methods?

[cscheid]

Different publishing targets will generally need different documentation. (eg, quarto pub doesn't support custom domains)

[cwickham]

I meant just the different methods of publishing GitHub pages (only those discussed on this doc page), as opposed to other publishing venues. I.e. should this exist as a top level section of "GitHub Pages" or as a subsection of the "Render to docs" section on that page.

[docsteveharris]

I came across this when trying to stop github pages over-writing my custom domain.
See https://stackoverflow.com/a/67184037, and so also would like to know that I can keep a CNAME file in the root.

[mcanouil]

You need to tell Quarto CNAME file is part of the website/document/book resources, see https://quarto.org/docs/websites/website-tools.html#site-resources.

This was also highlighted in a previous comment, see #4941 (comment).