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

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?

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

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.

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.

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).

From:

• docs: add a CNAME example for site resources quarto-web#1091

I believe so, because the other issue means to add something in the "publishing" parts of the website.

• keep the resource example because it shows the resource are not limited to file to be downloaded but also web related files.
• check/add that CNAME at the root of a Quarto project are automatically added to resources (possibly list other files that have the same treatment somewhere)
• add the custom domain setup to the relevant "publishing" pages.

I believe, we should use an include here.

Also from quarto-dev/quarto-web#1091:

Others are "robots.txt", ".nojekyll", "CNAME", "_redirects", "404.html"

• the 404.html detection at https://quarto.org/docs/websites/website-navigation.html#pages-404 (to use when 404.qmd is not desired)
• _redirects is mentioned in https://quarto.org/docs/websites/website-navigation.html#redirects but we don't say it will be detected
• .no-jekyll in https://quarto.org/docs/publishing/github-pages.html#render-to-docs by saying file should be created, and then quarto render. So implied I guessed
• robots.txt is not mentioned at all it seems

It makes sense to reiterate these files are automatically detected in https://quarto.org/docs/websites/website-tools.html#site-resources