Deploy Quartz to a subfolder on Neocities

I have very limited, almost nonexistent knowledge of GitHub and programming in general. I will try to explain all of this as best as possible.

My Visual Studio Code is set up like this:

My workspace has two repos. howsoonisnow is my main github repository. This is where my entire website lives. The Quartz repo lives inside the folder called quartz. Each time quartz is built, it builds to howsoonisnow/public/writings/ using a github workflow. Then a github workflow pushes any changes in /writings/ back to the howsoonisnow repository automatically.

howsoonisnow workflow:

1. Checks if anything changed in my local howsoonisnow/public
2. Publishes to Neocities

quartz workflow:

1. Builds the Quartz site
2. Copies the built pages into howsoonisnow
3. Pushes the changes to main

Quartz repo (v4)
   │
   └── builds site
           ↓
howsoonisnow/public/writings (main)
           ↓
       Deploys to Neocities

These two automated workflows:

• Automatically notice when I make changes
• Rebuild parts of my website
• Push new content
• Publish everything live
• Do all of this while allowing version control of everything

Here’s a visual overview of how everything fits together:

                +---------------------+
                |   Quartz Repository |
                |     (branch: v4)    |
                +---------------------+
                           │
                    [GitHub Action]
                           │
                           ▼
         +------------------------------------+
         |   howsoonisnow Repository (main)   |
         |   +----------------------------+   |
         |   | public/writings (from Quartz) |◄───┐
         |   +----------------------------+   |   │
         +------------------------------------+   │
                           │                      │
                    [GitHub Action]               │
                           │                      │
                           ▼                      │
              +---------------------------+       │
              |     Deployed to Neocities |◄──────┘
              +---------------------------+

This is not going to be an in-depth tutorial on how to install Quartz. If I can install it, then you can too, trust me. Assuming you have Quartz installed and we’re on the same page, here are templates of my github workflows that you can use and change depending on your needs:

Deploy to Neocities

name: Deploy to Neocities

on:
  push:
    branches:
      - main # or whatever your deployment branch is

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Deploy to Neocities
        uses: bcomnes/deploy-to-neocities@v3
        with:
          api_key: ${{ secrets.NEOCITIES_API_TOKEN }}
          dist_dir: public
          cleanup: true
          neocities_supporter: false # or true

Warning

You will need to set a NEOCITIES_API_TOKEN in your repo secrets to use this

Tip

I had cleanup set to false for a long time (it’s the default), but realized that if I deleted something from my repo, the file would still stay on Neocities. Even if it wasn’t linked anywhere, it would still be there. So now I’ve set cleanup: true — it makes sure Neocities only keeps what’s in the latest build and deletes anything that’s no longer part of the site.

Build and Deploy Quartz to Another Repo

This workflow assumes you want to push to the main branch of your target repo. Change it if your repo uses a different branch name.

name: Build and Deploy Quartz to Another Repo

on:
  push:
    branches:
      - v4

jobs:
  build-and-deploy:
    runs-on: ubuntu-22.04

    steps:
      - name: Checkout Quartz repository
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install dependencies
        run: npm ci

      - name: Clone target website repo
        env:
          REPO_URL: https://x-access-token:${{ secrets.TARGET_REPO_TOKEN }}@github.com/USERNAME/TARGET-REPO.git
        run: |
          git clone $REPO_URL ../target-repo

      - name: Build Quartz site
        run: npx quartz build

      - name: Replace output in target repo
        run: |
          rm -rf ../target-repo/public/writings
          mkdir -p ../target-repo/public
          mv public ../target-repo/public/writings

      - name: Commit and push changes
        env:
          COMMIT_EMAIL: github-actions[bot]@users.noreply.github.com
          COMMIT_NAME: github-actions[bot]
        run: |
          cd ../target-repo
          git config user.name "$COMMIT_NAME"
          git config user.email "$COMMIT_EMAIL"

          git add public/writings
          if git diff --cached --quiet; then
            echo "No changes to commit"
          else
            git commit -m "Update Quartz build output"
            git push origin main  # change to your target branch if needed

Warning

• Replace USERNAME/TARGET-REPO with the actual repo name.
• You need to set a TARGET_REPO_TOKEN secret (a personal access token) that has access to push to the other repo.