- Decide what is public first: a GitHub Pages site is on the open internet.
- On a computer, create a repo from the Quartz template, set
baseUrl, add thedeploy.ymlworkflow, and set Settings → Pages → Source to GitHub Actions. - Push once and confirm the site loads at
<user>.github.io/<repo>. - On your iPhone or iPad, clone the repo with GitSync.md into On My iPhone → Obsidian and open it in Obsidian.
- Write notes in
content/, then commit and push in GitSync.md. - 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
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
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: truein its frontmatter. Settingconfiguration.drafts.publish: truepublishes drafts anyway, so leave that off. - Publish only what you mark. The
ExplicitPublishplugin is in the defaultquartz.config.yamlbut disabled. Setenabled: trueon its entry and only notes withpublish: truein frontmatter are published. That is the safest choice for a vault with private notes. ignorePatterns. A list inquartz.config.yamlof fast-glob patterns that Quartz doesn't read at all, for example**/privatefor any file or folder namedprivate.- Attachments. By default (
publishAssets: "all") every non-Markdown file incontent/(images, PDFs, audio) is published, even if only an unpublished note uses it. SetpublishAssets: "referenced"to publish only files that published pages link to or embed.
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: - v5runs the workflow when you push tov5, the branch of the Quartz 5 template. This must match your repository's default branch. If yours is named differently, change it here.permissionslets the job publish to Pages.concurrencykeeps two deploys from running at once.fetch-depth: 0downloads the full Git history so Quartz can read each note's dates from Git.setup-nodewithnode-version: 24installs Node on the GitHub runner. The two cache steps just speed up later runs.npm ciinstalls the dependencies,npx quartz plugin installinstalls Quartz's plugins, andnpx quartz buildbuilds the site intopublic/.- The upload step packages
public/, and thedeployjob publishes it withactions/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
- Install GitSync.md from the App Store (iPhone and iPad) or Google Play (Android), and sign in to GitHub.
- 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.
- 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/.
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
quartzand 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
- In Obsidian, create
content/hello-from-iphone.md(a made-up example):
Quartz converts--- title: Hello from my iPhone --- This note was written on a phone. See also [[index]].[[wikilinks]]into normal links (Obsidian compatibility). Link to a note that exists incontent/;[[index]]works if your site has anindex.md. - 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%20notesyncpulls first, commits local changes with your message and pushes. Therepovalue should match the folder name shown in GitSync.md. - Open the repository's Actions tab on GitHub in your phone's browser. The deploy workflow starts from the push.
- 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 Pages | Obsidian Publish | |
|---|---|---|
| Hosting and cost | Free 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 it | GitHub Actions runs Quartz when you push | Obsidian's service |
| Publishing from mobile | Commit and push with a Git client such as GitSync.md | Check 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.
