GitHub_create_gh-pages_branch.md

Information on how to configure a new (empty) gh-pages branch and publish a quarto document there.

From: https://quarto.org/docs/publishing/github-pages.html#source-branch

Create GitHub Pages Source Branch (gh-pages)

Before attempting to publish you should ensure that the Source branch for your repository is gh-pages and that the site directory is set to the repository root (/).

If you do not already have a gh-pages branch, you can create one as follows:

• First, make sure you have committed all changes to your current working branch with git status.
• Then in terminal / Git Bash run:

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

• Double-check that the last git push action has indeed set the Settings : Pages for your repository as expected.
• Get back to your original repository branch with, for example: git checkout main

Ignoring Output

It's important to note that you don't need to check your _site or _book directory into version control. Before proceeding you should add the output directory of your project to .gitignore. For example, in .gitignore add:

/.quarto/
/_site/

If you've already checked these files into source control you may need to remove them explicitly. In Terminal / Git Bash run:

git rm -r _site

Publishing

Once you have configured the source branch and 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 (from 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.