Short version
  1. Decide what is public first: a GitHub Pages site is on the open internet.
  2. On a computer, create a repo from the Quartz template, set baseUrl, add the deploy.yml workflow, and set Settings → Pages → Source to GitHub Actions.
  3. Push once and confirm the site loads at <user>.github.io/<repo>.
  4. On your iPhone or iPad, clone the repo with GitSync.md into On My iPhone → Obsidian and open it in Obsidian.
  5. Write notes in content/, then commit and push in GitSync.md.
  6. Watch the GitHub Actions run, then reload your site.

This guide uses Quartz 5. Older tutorials describe Quartz v4 (quartz.config.ts, a v4 branch). Quartz 5 uses quartz.config.yaml, a v5 branch and a plugin install step, so don't mix the two. The commands below come from the Quartz installation docs and hosting docs; check them for changes before you start.

How the pieces fit

Obsidian (iPhone)
→
GitSync.md commit + push
→
GitHub repo
→
GitHub Actions (Quartz build)
→
GitHub Pages site

The phone never builds anything. GitSync.md clones the repository, Obsidian edits the Markdown files, and GitSync.md commits and pushes your changes. It doesn't run Node or Quartz and can't preview the site. The build happens on GitHub's servers in an Actions workflow. For the clone-and-edit part, see syncing Obsidian with Git on iPhone and iPad and syncing Obsidian with GitHub on every device.

What will be public

Read this before you set anything up

GitHub says Pages sites are publicly available on the internet, even if the repository behind them is private (where your plan allows that). See About GitHub Pages, and check GitHub's docs for which plans can publish Pages from a private repository. Treat everything that reaches the built site as published.

Quartz has several ways to keep notes out of the site. They are described on its Private Pages docs page:

  • Drafts. By default Quartz leaves out any note with draft: true in its frontmatter. Setting configuration.drafts.publish: true publishes drafts anyway, so leave that off.
  • Publish only what you mark. The ExplicitPublish plugin is in the default quartz.config.yaml but disabled. Set enabled: true on its entry and only notes with publish: true in frontmatter are published. That is the safest choice for a vault with private notes.
  • ignorePatterns. A list in quartz.config.yaml of fast-glob patterns that Quartz doesn't read at all, for example **/private for any file or folder named private.
  • Attachments. By default (publishAssets: "all") every non-Markdown file in content/ (images, PDFs, audio) is published, even if only an unpublished note uses it. Set publishAssets: "referenced" to publish only files that published pages link to or embed.
Hidden from the site is not hidden from the repo

These settings only affect the built site. If the repository is public, anyone can read the Markdown source. The Quartz docs say to also add private paths to your .gitignore so they are never committed. Quartz's own .gitignore already lists private/, but a folder ignored by Git is also not backed up or synced by Git, so notes you must keep private are better in a separate private repository.

Keep secrets out of the repo too: no tokens, passwords or API keys in notes or config files. If one is committed, adding an ignore rule doesn't remove it from history; revoke it first, as the .gitignore guide explains.

One-time setup on a computer

You need Node.js 22 or later, Git and a GitHub account, per the installation docs. Node and npm run on the computer, not on your phone.

Create the repo and preview locally

On the Quartz repository, use the template (the docs' Option A) to create your own repository, for example my-garden. Then clone it and run the setup:

git clone https://github.com/<your-username>/my-garden.git
cd my-garden
npm i
npx quartz create

The create wizard asks for a template (default, obsidian, ttrpg, blog or docs), how to fill content/, a base URL without https://, and a link resolution strategy. Then preview the site:

npx quartz build --serve

Open http://localhost:8080. It reloads when files change.

Set baseUrl before the first deploy

In quartz.config.yaml, baseUrl is the address where your site lives, without the protocol or leading and trailing slashes. For a GitHub Pages project site that is <user>.github.io/<repo>, for example example-user.github.io/my-garden. The hosting docs say the RSS feed and sitemap need it: "Make sure you set this before deploying!"

Add the deploy workflow

Create .github/workflows/deploy.yml at the repository root with the workflow from the GitHub Pages section of the hosting docs. On November 22, 2026 it read:

name: Deploy Quartz site to GitHub Pages

on:
  push:
    branches:
      - v5

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0 # Fetch all history for git info
      - uses: actions/setup-node@v6
        with:
          node-version: 24
      - name: Cache dependencies
        uses: actions/cache@v5
        with:
          path: ~/.npm
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-node-
      - name: Cache Quartz plugins
        uses: actions/cache@v5
        with:
          path: .quartz/plugins
          key: ${{ runner.os }}-plugins-${{ hashFiles('quartz.lock.json') }}
          restore-keys: |
            ${{ runner.os }}-plugins-
      - name: Install Dependencies
        run: npm ci
      - name: Install Quartz plugins
        run: npx quartz plugin install
      - 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

In plain words:

  • on: push: branches: - v5 runs the workflow when you push to v5, the branch of the Quartz 5 template. This must match your repository's default branch. If yours is named differently, change it here.
  • permissions lets the job publish to Pages. concurrency keeps two deploys from running at once.
  • fetch-depth: 0 downloads the full Git history so Quartz can read each note's dates from Git.
  • setup-node with node-version: 24 installs Node on the GitHub runner. The two cache steps just speed up later runs.
  • npm ci installs the dependencies, npx quartz plugin install installs Quartz's plugins, and npx quartz build builds the site into public/.
  • The upload step packages public/, and the deploy job publishes it with actions/deploy-pages.

Action versions change. If the hosting docs show newer ones when you read this, use theirs.

Turn on GitHub Pages and push

In your repository, open Settings → Pages and set Source to GitHub Actions (GitHub: Configuring a publishing source). Then commit and push. The Quartz docs use npx quartz sync; for a first push with nothing to pull, they give:

npx quartz sync --no-pull

A plain git add, git commit and git push works too. Watch the run in the repository's Actions tab. When it finishes, your site should be at <user>.github.io/<repo>.

Check what got committed

Run git status and make sure the build output (public/), node_modules/ and Quartz's caches aren't tracked. Quartz's own .gitignore lists public, node_modules, .quartz-cache, .quartz/, .obsidian and private/, so keep those lines. If you add rules, see the Obsidian .gitignore guide.

Put the repo on your iPhone or iPad

  1. Install GitSync.md from the App Store (iPhone and iPad) or Google Play (Android), and sign in to GitHub.
  2. When it asks for a default save location, choose On My iPhone → Obsidian (on iPad, On My iPad → Obsidian). The Obsidian Git iOS setup guide shows this step.
  3. Clone your Quartz repository. The clone guide covers HTTPS and SSH remotes in detail.

Get GitSync.md for iPhone and iPad → · Get it on Google Play →

Open it in Obsidian

In Obsidian's vault picker choose Open folder as vault and select the cloned folder. The repository root becomes the vault, so Quartz's own source files (quartz/, package.json, the workflow) show up next to your notes. Your notes belong in content/.

Avoid nested vault confusion

Open the repository root, the folder that contains .git, not its parent or a subfolder. See the nested-vault warning in the Obsidian Git guide.

Two settings under Settings → Files and links make this tidier (see Obsidian's settings help):

  • Excluded files: add quartz and other non-note folders. Obsidian hides excluded files in Search, Graph view and Unlinked mentions. This only changes what Obsidian shows; Git and Quartz are unaffected.
  • Default location for new notes: choose a folder you specify and enter content, so new notes land where Quartz reads them.

Daily loop: write, push, live

  1. In Obsidian, create content/hello-from-iphone.md (a made-up example):
    ---
    title: Hello from my iPhone
    ---
    
    This note was written on a phone. See also [[index]].
    Quartz converts [[wikilinks]] into normal links (Obsidian compatibility). Link to a note that exists in content/; [[index]] works if your site has an index.md.
  2. Open GitSync.md, review the changed file, then commit and push. Or tap a link in a note:
    syncmd://x-callback-url/sync?repo=my-garden&message=Add%20hello%20note
    sync pulls first, commits local changes with your message and pushes. The repo value should match the folder name shown in GitSync.md.
  3. Open the repository's Actions tab on GitHub in your phone's browser. The deploy workflow starts from the push.
  4. When the run is green, reload <user>.github.io/<repo>/hello-from-iphone.

Optionally, build a Shortcut that runs GitSync.md's sync action so publishing is one tap. It is still something you trigger. For what automatic sync can and can't do on iOS, read the background sync guide.

Troubleshooting

The site shows a 404 or old content

Check Settings → Pages → Source is GitHub Actions. Confirm the workflow's branches: value matches the branch you pushed to, then look in the Actions tab for a failed run. Per the hosting docs, hosted builds fail on a broken plugin instead of publishing a site without it; run npx quartz plugin doctor on your computer to find the cause.

Links or RSS point to the wrong place

baseUrl is probably wrong or missing in quartz.config.yaml. It must be the deployed address without https:// or slashes (hosting docs).

A draft got published

Check the note has draft: true (or has no publish: true if you enabled ExplicitPublish) and that drafts.publish isn't true. Images and PDFs also publish by default; see publishAssets above (Private Pages). A page that was already live stays readable in the repository's history, so remove sensitive content from Git as well.

A push is rejected when you edit the workflow from your phone

A token that changes files under .github/workflows needs the workflow scope; ordinary note edits don't. The scope note is in the Personal Access Token guide. Simpler: change the workflow on your computer.

A pull conflict after editing on two devices

Follow Fix Obsidian Git merge conflicts on iPhone, then push again.

Quartz vs Obsidian Publish

Quartz + GitHub PagesObsidian Publish
Hosting and costFree static site you host yourself on GitHub Pages (plan limits apply to private repos)Hosted service by Obsidian; see Obsidian's Publish page for the current price
Who builds itGitHub Actions runs Quartz when you pushObsidian's service
Publishing from mobileCommit and push with a Git client such as GitSync.mdCheck Obsidian's Publish page for how it works in the mobile app

FAQ

Do I need a computer?

Yes, once. Quartz setup needs Node.js 22 or later and a terminal. After that, writing and publishing happen from your phone.

Can the GitHub repository be private?

Yes, but the published site is still public, and GitHub limits which plans can use Pages with private repositories. See About GitHub Pages. GitSync.md can clone private repositories.

Can I use Cloudflare Pages or Netlify instead?

Yes. The Quartz hosting docs have sections for other hosts, and the phone workflow (commit and push) stays the same. Their build settings differ from the GitHub workflow above, so follow the docs for your host.

Does this work on Android?

The push-to-publish loop is the same with a Git client on Android. See Obsidian Git on Android for the options, including GitSync.md on Google Play.

Related guides