docs: add a CNAME example for site resources

[mcanouil]

This pull request adds an example in the documentation for including a CNAME file in the resources list in the _quarto.yml configuration file.

This better illustrate that resources can be used more widely and in a more web driven way, such as publishing using domain, etc.

FYI: quarto-dev/quarto-cli#5341

[cderv]

/deploy-preview

[cderv]

I think CNAME is among the files that we will detect by default in a project and consider as resources to move in the output dir https://github.com/quarto-dev/quarto-cli/blob/a5e1f3be842e0c4d33b6b87214f4f1daae93a384/src/project/project-resources.ts#L57-L60

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

So it should not be necessary to add to resources. Does it works ?

We don't document those files yet though...

[github-actions[bot]]

🚀 Deployed on https://deploy-preview-1091--mystifying-jepsen-fa4396.netlify.app

[mcanouil]

Are you sure it works as expected? (I was not aware of this) The discussion was "reopen" few days ago because the CNAME was erased.

The codepath means the CNAME needs to be at the root of the source code, but does not block Quarto from cleaning up the output directory. In my understanding, it means, the users need to know, they had to place the file next to _quarto.yml and not next to /index.html. This is not obvious.

[cderv]

output-dir will always be erased for a new rendering. This is, for now, how Quarto works. So, any files that need to be in the output directory must also be in the source directory or created by the rendering. Any files (not just CNAME or others) created in the output directory will be deleted at the next rendering.

resources is indeed a way to have some files copied. But we support some known filenames for websites like the one I shared. I don't know if this is still working, as I did not test it, but our codebase assumes it should.

However, as I said, this is not fully documented as clearly AFAIK. So I think we should document this instead of just adding an example for CNAME with a method that is not required as we have the detection feature.

We document somewhat

• 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

So probably a part in website regarding those files could be added, or a clarification in each feature related paragraph for what is not obvious.

[mcanouil]

FYI:

• https://github.com/quarto-dev/quarto-cli/issues/4941

[cderv]

Yep, we could also close this one by documenting correctly all this ! Thanks for linking the issue.

Should we put this as draft and start working on it again ?

[mcanouil]

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.