github-pages.qmd

---
title: "GitHub Pages"
editor: visual
provider:
  id: gh-pages
  name: GitHub Pages
---

## Overview

[GitHub Pages](https://pages.github.com/) is a website hosting service that enables you to publish content based on source code managed within a GitHub repository.

There are three ways to publish Quarto websites and documents to GitHub Pages:

1.  Render sites on your local machine to the `docs` directory, check the rendered site into GitHub, and then configure your GitHub repo to publish from the `docs` directory.

2.  Use the `quarto publish` command to publish content rendered on your local machine.

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](#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}

The simplest way to publish using GitHub Pages is to render to the `docs` directory and then check that directory into your repository. If you prefer not to check rendered output into version control see the discussion of using [Publish Command](#publish-command) below.

To get started, change your project configuration to use `docs` as the `output-dir`. For example:

``` {.yaml filename="_quarto.yml"}
project:
  type: website
  output-dir: docs
```

Then, add a `.nojekyll` file to the root of your repository that tells GitHub Pages not to do additional processing of your published site using Jekyll (the GitHub default site generation tool):

+---------------+---------------------------------+
|               |                                 |
+===============+=================================+
| Mac/Linux     | ``` {.bash filename="Terminal"} |
|               | touch .nojekyll                 |
|               | ```                             |
+---------------+---------------------------------+
| Windows       | ``` {.bash filename="Terminal"} |
|               | copy NUL .nojekyll              |
|               | ```                             |
+---------------+---------------------------------+

Now, render your site and push it to GitHub:

``` {.bash filename="Terminal"}
quarto render
git add docs
git commit -m "Publish site to docs/"
git push
```

Finally, configure your GitHub repository to publish from the `docs` directory of your `main` branch:

![](images/gh-pages-docs-dir.png){.border}

Once you've made this configuration change GitHub will trigger a deployment of your website. Your site will also be updated whenever you commit and push to `main`.

## Publish Command {#publish-command}

The `quarto publish` command is an easy way to publish locally rendered documents and websites. Before attempting to use `quarto publish` (either locally or from a GitHub Action) you should be sure to configure [Ignore Output](#ignoring-output) as described below. See [Source Branch](#source-branch) for an overview of how the `gh-pages` branch is managed.

### Source Branch {#source-branch}

`quarto publish gh-pages` automatically creates a `gh-pages` branch (locally and on the remote) on its first run if one does not already exist. For most repositories --- the typical [project site](https://docs.github.com/en/pages/getting-started-with-github-pages/what-is-github-pages#types-of-github-pages-sites) case where the URL is `https://<username>.github.io/<repo>/` --- GitHub then detects the new branch and configures GitHub Pages to deploy from it automatically. No manual configuration under **Settings** : **Pages** is required.

[User and organization sites](https://docs.github.com/en/pages/getting-started-with-github-pages/what-is-github-pages#types-of-github-pages-sites) (served at `https://<username>.github.io/`) behave differently on the GitHub side: their [default publishing source is the `main` branch](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-from-a-branch), not `gh-pages`. After the first run of `quarto publish gh-pages` you therefore need to switch the source branch to `gh-pages` manually under **Settings** : **Pages** for your repository:

![](images/gh-pages-user-site.png){.border}

Quarto prints a notice with a direct link to this settings page when it detects this case. See the [User Site](#user-site) section below for the complete setup.

::: {.callout-tip collapse="true"}
## Creating a `gh-pages` branch manually

You usually do not need to do this --- `quarto publish gh-pages` will create the branch on its first run. If you prefer to set it up yourself beforehand, first make sure you have committed all changes on your current working branch with `git status`, then run:

``` {.bash filename="Terminal"}
git checkout --orphan gh-pages
git reset --hard # make sure all changes are committed before running this!
git commit --allow-empty -m "Initialising gh-pages branch"
git push origin gh-pages
```

Get back to your original repository branch with, for example, `git checkout main`.
:::

### Ignoring Output {#ignoring-output}

{{< include _ignoring-output.md >}}

### Publishing

Once you have updated your `.gitignore`, navigate to the directory where your project / git repository is located, make sure you are not on the `gh-pages` branch, and execute the `quarto publish` command for GitHub Pages:

``` {.bash filename="Terminal"}
quarto publish gh-pages
```

The publish command will confirm that you want to publish, render your content, copy the output to a special `gh-pages` branch, push that branch to GitHub, and then open a browser to view your site once it is deployed.

#### Private Sites

If you are publishing to a private (i.e. password protected) website then the logic within `quarto publish`that waits for your site to be available before opening a browser won't work correctly. In this case you should pass the `--no-browser` option to bypass this:

``` {.bash filename="Terminal"}
quarto publish gh-pages --no-browser
```

#### Documents

To publish a document rather than a website or book, provide the path to the document (note that you can publish only one document from a given GitHub repository):

``` {.bash filename="Terminal"}
quarto publish gh-pages document.qmd
```

#### Options

Here are all of the available command line options for `quarto publish gh-pages`:

{{< include _cli-options.md >}}

## GitHub Action {#github-action}

Using the `quarto publish {{< meta provider.id>}}` command to publish locally rendered content is the most simple and straightforward way to publish. Another option is to use [GitHub Actions](https://docs.github.com/en/actions) to render and publish your site (you might prefer this if you want execution and/or rendering to be automatically triggered from commits).

There are a few different ways to approach rendering and publishing content. Below, we'll provide a how-to guide for publishing with GitHub Actions. For more conceptual background on the various approaches, see the discussion on [Rendering for CI](ci.qmd#rendering-for-ci).

### Freezing Computations

{{< include _freeze-basics.md >}}

Note that an alternative approach is to execute the code as part of the GitHub Action. For now we'll keep things simpler by executing code locally and storing the computations by using freeze. Then, further below, we'll cover [Executing Code](#executing-code) within a GitHub Action.

### Publish Action

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:

``` bash
quarto publish gh-pages
```

Once you've completed a local publish, add a `publish.yml` GitHub Action to your project by creating this YAML file and saving it to `.github/workflows/publish.yml`:

``` {.yaml filename=".github/workflows/publish.yml"}
on:
  workflow_dispatch:
  push:
    branches: main

name: Quarto Publish

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2

      - name: Render and Publish
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: {{< meta provider.id>}}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

This action will run whenever you push to the `main` branch of your repository. It will also run when you manually trigger the action from the **Actions** tab of your repository. The action will render your content and publish it to GitHub Pages, thus you need to ensure that GitHub Actions has permission to write to your repository. This is done by checking the **Read and write permissions** box under **Workflow permissions** in the **Actions** section of your repository **Settings**.

Once you've done this, check all of the newly created files (including the `_freeze` directory) into your repository and then push to GitHub. A GitHub Pages site will be created for your repository, and every time you push a new change to the repository it will be automatically rebuilt to reflect the change. Consult the **Pages** section of your repository **Settings** to see what the URL and publish status for your site is.

{{< include _github-action-executing-code.md >}}

### Example: Jupyter with venv

Here is a complete example of a GitHub Action that installs Python, Jupyter, and package dependencies from `requirements.txt`, then executes code and renders output to GitHub Pages:

``` {.yaml filename=".github/workflows/publish.yml"}
on:
  workflow_dispatch:
  push:
    branches: main

name: Quarto Publish

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2

      - name: Install Python and Dependencies
        uses: actions/setup-python@v5
        with:
          python-version: '3.10'
          cache: 'pip'
      - run: pip install jupyter
      - run: pip install -r requirements.txt

      - name: Render and Publish
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: gh-pages
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

### Example: Knitr with renv

Here is a complete example of a GitHub Action that installs R and package dependencies from `renv.lock`, then executes code and renders output to GitHub Pages:

``` {.yaml filename=".github/workflows/publish.yml"}
on:
  workflow_dispatch:
  push:
    branches: main

name: Quarto Publish

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2

      - name: Install R
        uses: r-lib/actions/setup-r@v2
        with:
          r-version: '4.2.0'

      - name: Install R Dependencies
        uses: r-lib/actions/setup-renv@v2
        with:
          cache-version: 1

      - name: Render and Publish
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: gh-pages
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

### Additional Options

It's possible to have a Quarto project in a larger GitHub repository, where the Quarto project does not reside at the top-level directory. In this case, add a `path` input to the invocation of the `publish` action. For example:

``` yaml
- name: Render and Publish
  uses: quarto-dev/quarto-actions/publish@v2
  with:
    target: {{< meta provider.id>}}
    path: subdirectory-to-use
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

By default, `quarto publish` will re-render your project before publishing it. However, if you store the rendered output in version control, you don't need the GitHub action to re-render the project. In that case, add the option `render: false` to the `publish` action:

``` yaml
- name: Render and Publish
  uses: quarto-dev/quarto-actions/publish@v2
  with:
    target: {{< meta provider.id>}}
    render: false
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

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 records with your DNS provider

### 1. Add your domain to your GitHub repository settings

Add a `CNAME` file to your project root directory (i.e., alongside `_quarto.yml`) that contains your custom domain:

::: {layout-ncol="2"}
``` {.default filename="website/"}
├── _site/
├── _quarto.yml
├── CNAME
├── about.qmd
└── index.qmd
```

``` {.default filename="CNAME"}
blog.example.com
```
:::

Quarto will recognize 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.

Re-render and publish your site to ensure `CNAME` is available to GitHub Pages.

::: callout-note
The GitHub Pages documentation 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 with Quarto.
:::

### 2. Configure records with your DNS provider

The records you need to configure with your DNS provider depend on whether you are using an apex domain (e.g., `example.com`) or a subdomain (e.g., `www.example.com` or `blog.example.com`).

Apex domains require an `ALIAS`, `ANAME`, or `A` record, whereas subdomains require a `CNAME` record. Find the appropriate values from the [DNS records summary table in 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#dns-records-for-your-custom-domain). For apex domains, pay particular attention to the DNS record values, you may need to overwrite addresses your DNS provider has added by default.

## 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:

1.  Create a Git repo with the name `username.github.io` (where "username" is your GitHub username) and sync it to your local machine.

2.  Set the **Source** branch for your user site to `gh-pages` as described in [Source Branch](#source-branch).