Add custom domain set up to Github Pages (#1583) (#1584)

* Custom domain details

* Add note about recognized files

(cherry picked from commit 6e3ca3e)

Co-authored-by: Charlotte Wickham <[email protected]>

Author: github-actions[bot]

docs/publishing/github-pages.qmd

@@ -15,11 +15,11 @@ There are three ways to publish Quarto websites and documents to GitHub Pages:
 
 2.  Use the `quarto publish` command to publish content rendered on your local machine.
 
-3.  Use a [GitHub Action] to automatically render your files (a single Quarto document or a Quarto project) and publish the resulting content whenever you push a source code change to your repository.
+3.  Use a [GitHub Action](#github-action) to automatically render your files (a single Quarto document or a Quarto project) and publish the resulting content whenever you push a source code change to your repository.
 
 We'll cover each of these methods below, but first an important pre-requisite: you need to have a Git repository on your local machine that is synced to GitHub. The URL of the published website will be derived from the combination of your username and the repository name (e.g. `https://username.github.io/reponame/`).
 
-You can optionally configure a [custom domain](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages) for a GitHub Pages site, but before exploring that ground you should get your site up and running with the default domain.
+You can optionally configure a [custom domain](#custom-domain) for a GitHub Pages site, but before exploring that, get your site up and running with the default domain.
 
 ## Render to `docs` {#render-to-docs}
 
@@ -283,6 +283,40 @@ By default, `quarto publish` will re-render your project before publishing it. H
 
 See the full definition of the Quarto [publish action](https://github.com/quarto-dev/quarto-actions/blob/main/publish/action.yml) to learn about other more advanced options.
 
+## Custom Domain {#custom-domain}
+
+A custom domain allows you to use your own domain name instead of the default `username.github.io` domain for your GitHub Pages site.
+To use a custom domain you need to complete two steps:
+
+1. Add your domain to your GitHub repository settings
+2. Configure a record with your DNS provider
+
+For the first step, the [GitHub Pages documentation](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site) describes adding your domain to your repository in the  **Settings** pane. 
+However, this creates a `CNAME` file in the location of your rendered site, 
+which will be overwritten whenever you render your site.
+Instead, create a `CNAME` file manually in your project root directory (i.e. alongside `_quarto.yml`):
+
+::: {layout-ncol="2"}
+
+```{.default filename="website/"}
+├── _site/
+├── _quarto.yml
+├── CNAME
+├── about.qmd
+└── index.qmd
+```
+
+```{.default filename="CNAME"}
+blog.example.com
+```
+::::
+
+Quarto recognizes the `CNAME` file as a [site resource](/docs/websites/website-tools.qmd#site-resources) and will copy it your site output directory when you render.
+Commit `CNAME` (and `docs/CNAME`, if you are publishing from `docs/`), 
+and push to GitHub before completing the second step. 
+
+Learn more about the second step, and troubleshooting tips in the [GitHub Pages documentation](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages).
+
 ## User Site
 
 In addition to creating sites tied to various repositories, you can also create a user site that is served from your root user domain (e.g. `https://username.github.io`). This is an ideal place to publish a blog or personal home page. To create a user site:

docs/websites/website-tools.qmd

@@ -359,6 +359,14 @@ An example script that is used for user tracking would look like:
 
 Besides input and configuration files, your site likely also includes a variety of resources (e.g. images) that you will want to publish along with your site. Quarto will automatically detect any files that you reference within your site and copy them to the output directory (e.g. `_site`).
 
+Quarto also recognizes the following files and copies them to your output directory: 
+
+* `404.html`, one option for providing a [404 Page](/docs/websites/website-navigation.qmd#pages-404)
+* `robots.txt`, a file specified by the [Robots Exclusion Protocol](https://datatracker.ietf.org/doc/html/rfc9309){.external} that tells search engine crawlers which pages or files on your website they can or cannot access
+* `_redirects`, a file used by some publishing providers to provide page redirects, e.g. [Netlify](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file){.external}
+* `CNAME`, a file used by some publishing providers to specify a custom domain, e.g. [GitHub Pages](/docs/publishing/github-pages.qmd#custom-domain)
+* `.nojekyll`, a file used by GitHub pages to bypass building with Jekyll, e.g. when [publishing from `docs/`](/docs/publishing/github-pages.qmd#render-to-docs)
+
 If this auto-detection fails for any reason, or if you want to publish a file not explicitly linked to from within your site, you can add a `resources` entry to your configuration. For example, here we specify that we want to include all Excel spreadsheets within the project directory as part of the website:
 
 ``` {.yaml .yml}