11.02 - Quartz

Info

Quartz is software that generates web pages using markup files, you can use it to host documents or digital gardens and the like. I myself use it to host my notes and documentation on anything i feel like.

In this document I’ll explain how to install quartz and how to host it on github pages to host it (for free!)

Installing Quartz

official documentation

If you want to follow the steps from the official site, go to https://quartz.jzhao.xyz/ (or look at it if you want to do anything apart installing it or hosting it on github pages)

prequesites

• Node V20 (at least)
• git

Open up your command terminal (for example cmd) at the directory you want to install quartz at and type in the following commands line by line:

git clone https://github.com/jackyzha0/quartz.git
cd quartz
npm i
npx quartz create

This will create a quartz folder with everything you need to create a quartz page.

Syncing up quartz to your git repository

To sync quartz between devices (or to host it on github pages) you need to create an empty repository on github.

1. go to https://github.com and log in (or create an account)
2. on your dashboard in the top left, press the green new button
3. Give your repository a name (i named mine quartz)
4. dont change anything else (keep the repository visibility on Public)
5. click Create repository
6. Inside your repository, click the green Code button and copy the https url eg: https://github.com/<username>/<repository>.git
7. Open up your command terminal inside the quartz root folder and type the following command lines:

# list all the repositories that are tracked
git remote -v 
 
# if the origin doesn't match your own repository, set your repository as the origin
git remote set-url origin <the url you copied> 
 
# if you don't have upstream as a remote, add it so updates work
git remote add upstream https://github.com/jackyzha0/quartz.git

The end result should look something like this:

If everything went correctly you can initialise the sync by running:

npx quartz sync --no-pull

if you got an autostash error

Try updating your git

In the future you can run: npx quartz sync to sync to github

Writing markdown Inside quartz

Inside the content folder in your quartz folder, you can make markdown files (and folders) for quartz to read. If you’re using [obsidian]content-to-come, you need to open the content folder inside obsidian and start working in there.

Previewing your quartz page

If you have installed quartz, wrote something inside, and want to preview your page, You can run the following command (while being in the quartz root directory) inside your terminal of choice:

npx quartz build --serve

The page will be shown at http://localhost:8080 and will automatically update if you edit/create/delete files _{(for some command flags and options, look at the official documentation)}

Hosting your quartz page on github pages

if you installed and Syncing up quartz to your git repository your quartz page, you’re ready to host it on github too. It’s pretty simple and straight forward

Inside your local quartz folder, create a new file quarts/.github/workflows/deploy.yml and paste the following text into it:

name: Deploy Quartz site to GitHub Pages
 
on:
  push:
    branches:
      - v4
 
permissions:
  contents: read
  pages: write
  id-token: write
 
concurrency:
  group: "pages"
  cancel-in-progress: false
 
jobs:
  build:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Fetch all history for git info
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Install Dependencies
        run: npm ci
      - name: Build Quartz
        run: npx quartz build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: public
 
  deploy:
    needs: build
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

After that, head to your quartz repository on github and in the navigation bar, head to Settings, Pages, and under source (build and deployment), select github actions. Sync your local changes by typing npx quartz sync in your command terminal and the site should deploy to .github.io/

using a custom domain

If you want to use a custom domain name, you need to buy one from a domain website and follow this tutorial