3. Setup-External Services

Github

Create Github Authorization Token

• In a browser navigate to http://github.com

• Navigate to Settings menus:
  • Settings (Under menu opened from user icon in top right)
  • Developer Settings
  • Personal Access Tokens
• Choose “Tokens (classic)”
• Generate new token
• Required scopes:
  • repo (Full control of private repositories)
  • workflow (for GitHub Actions)

Create Mirror

A gitea mirror will be used to automatically sync the local gitea repo to github. This lets content to be developed locally and all for all external access to be handle by github instead of locally.

• Create empty github repo to mirror

• In a browser navigate to your quartz gitea repo
• Open Settings with wrench icon near right hand side of screen
• Find “Push Mirrors” section
• Add push mirror with:
  • Remote URL: https://github.com/YOUR_USERNAME/{repo_name}
  • Username: Your GitHub username
  • Password: Your GitHub PAT
  • Click “Add Push Mirror”

Setup Pages

Github pages will be used to freely host the quartz website.

• In a browser navigate to http://github.com/{username}/{repo_name}
• Open repository settings noted with gear icon near top of screen

• Navigate to “Pages” in the sidebar
• Under “Source”, select “Deploy from a branch”
• Choose “v4” branch and “/docs” folder
• Click Save

Update the Gitea Action

Currently the gitea repo does not organize the repo in a supported structure for github pages. Move contents of public folder docs folder. Add CNAME so custom domain is setup correctly in github pages.

• Pull down the gitea repo for quartz
• Update the build.yml file based on contents shown below
• Commit and push the changes

name: Build Quartz Site
 
on:
	push:
	   paths-ignore:
	    - 'docs/**' 
 
jobs:
build:
	runs-on: ubuntu-latest
	steps:
	- name: Checkout repository
	  uses: actions/checkout@v4
 
	- name: Setup Node.js
	  uses: actions/setup-node@v4
	  with:
		node-version: '20'
 
	- name: Install dependencies and build
	  run: |
		npm install
		npm audit fix
		npx quartz build
		
	- name: Move built files to docs
	  run: |
		rm -rf docs
		mv public docs
		echo "doimain_name.net" > docs/CNAME
 
	- name: Commit and push built site
	  run: |
		git config --global user.name "Gitea Actions"
		git config --global user.email "{}"
		git add docs/
		
		if git status --porcelain | grep .; then
		  git commit -m "Build site $(date +'%Y-%m-%d %H:%M:%S')"
		  git push origin HEAD
		else
		  echo "No changes to commit"
		fi

Verify Github Page

• By pushing the change locally in gitea the mirror should have automatically updated github
• Navigate in a browser to the gitlab page: http://{username}.github.io/{repo_name}
• You should now see the default quartz page, if you do not check the follow:
  • The local gitea repo was pushed with the lastest commit
  • The github repo was mirror and properly has the commit with the current date and change

Git Repo Clean up

If there are a bunch of branches in the original repo these can be removed from our gitea repo:

• In a browser navigate to your local gitea quartz repo
• click on branches
• Use the trash can icons to delete all the extraneous branches
• You can now manually sync the repos in the repository setting to update github. Note: you may need to change the default repo in the github repo to align with the default repo in gitea: v4

Cloudflare

DNS Setup:

• Log into Cloudflare
• Select your domain
• Add a new DNS record:
  • Type: CNAME
  • Name: www (or your preferred subdomain)
  • Target: username.github.io
  • Proxy status: Proxied (orange cloud)

Add Custom Domain in GitHub:

• Back in GitHub Pages settings
• Under “Custom domain”
• Enter your full domain (e.g., www.yourdomain.com)
• Save and wait a few minutes DNS verification
• Navigate to your domain (www.yourdomain.com) and verify the site is operable