How to create a website from Quarto

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

Download and install Quarto CLI from https://quarto.org/docs/download/
Open your terminal and go to your working directory (e.g. ~/projects/sunny-bak/)
Create a quarto scaffolding for your project (template) called funsite; This process creates template quarto pages
- _quarto.yml : specifies how your website should be structured (menu position, menu item names, etc.)
- index.qmd, about.qmd (or rename from .qmd to .md if computation is not needed) : markdown file including content for index.html and about.html respectively
- _sites : temporary directory to store dynamically generated html files by quarto

# create scaffolding
quarto create-project funsite --type website 

# go to website directory
cd funsite

# preview the template website
quarto preview

Create a local git repository and remote repository with the same name (funsite)

# initialize git repo (main branch)
git init
git add .
git commit -m "initl commit"
git branch -M main

# make sure to create funsite remote repository on Github first
git remote add origin git@github.com:[your-github]/funsite.git
git push -u origin main

# create and gh-pages branch
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

Before publishing, make sure to edit .gitignore page to exclude temp files and update repo. If you already checked them, remove them by git rm -r _site

# .gitignore
/.quarto/
/_site/

Publish using quarto publish gh-pages or using Github Action.

Setting up Github Action

We want to set up a github action to

automatically render and publish our content when we push to the main branch
manually use the Actions tab to trigger the action of rendering/publishing

We will set up the github Action so website update is automatically executed upon new commit to the main branch.

Create a file in .github/workflows/deploy.yaml and copy and paste the following:

# .github/workflows/deploy.yaml
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: gh-pages
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Go to the repository Settings -> Actions -> General -> Select Read and write permissions under Workflow permissions
Go to the repository Settings -> Pages -> Select deploy from a branch -> gh-pages and root/