Setup Guide

A GitHub account is required to use Quartz and Quartz Syncer

You can sign up for free here.

Set up Quartz first

This plugin manages Quartz content from Obsidian. Please set up Quartz if you have not already. See instructions below.

Set up Quartz

Create Quartz GitHub repository

If you haven’t set up a Quartz repository on GitHub yet, click here to create it using the Quartz template.

Configure Quartz settings

Configure quartz.config.ts

Configure the following settings in the quartz.config.ts file:

(Below example only shows a subset of all settings. Please do not remove any settings.)

quartz.config.ts

const config: QuartzConfig = {
  configuration: {
    pageTitle: "Quartz 4",
    // Change to your desired site title
    ...
    baseUrl: "quartz.jzhao.xyz",
    // Change to your site URL without https://.
    // This is your own domain,
    // or "<github-user-name>.github.io/<repository-name>" when using GitHub Pages.
    // See below for details
    ...
    defaultDateType: "modified",
    // Change to tell Quartz what date to display on notes
    // Valid options:
    // "created", use when the note was created.
    // "modified", use when the note was last modified.
    // "published", use when the note was published.
    // See Quartz docs for details.
    ...
    }
  }
  plugins: {
    transformers: [
      ...
      Plugin.CrawlLinks({ markdownLinkResolution: "shortest" }),
      // Sets how Quartz should resolve links between notes.
      // Should match the settings you use in Obsidian.
      // Valid options:
      // "shortest"
      // "relative"
      // "absolute"
      ...
    ]
    ...
  }
}

Configure automatic deployment

If you haven’t already, set up Quartz to automatically deploy on push:

GitHub Pages setup (recommended)

In your GitHub repository, go to Settings > Pages and set Source to “GitHub Actions”.

Next, add one of the following deploy scripts:

Option 1: Default Quartz

For using Quartz without adding an Obsidian Theme.

Add the following script as .github/workflows/deploy.yaml:

.github/workflows/deploy.yaml

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

Option 2: Quartz with Quartz Themes

For using an Obsidian Theme with Quartz.

Don't forget to replace THEME_NAME with your Obsidian theme of choice A list of theme options can be found here.

Add the following script as .github/workflows/deploy.yaml:

.github/workflows/deploy.yaml

name: Deploy Quartz site to GitHub Pages
 
on:
  push:
    branches:
      - v4
 
env:
  THEME_NAME: tokyo-night
 
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: Fetch Quartz Theme
        run: curl -s -S https://raw.githubusercontent.com/saberzero1/quartz-themes/master/action.sh | bash -s -- $THEME_NAME 
      - 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

For other options, see the Quartz docs on hosting.

Generating a fine-grained access token

1. Go to this page and apply the following settings:
2. Token name: The name to identify this token. I’d recommend something that indicates it is for Quartz Syncer, like Quartz Syncer token.
3. Expiration: When this token will expire. Defaults to 30 days from now. GitHub will send you an email when your token is about to expire.
4. Repository access: Select Only select repositories and in the drop-down select your Quartz repository.
5. Permissions: Click Repository permissions to open all options.
6. Scroll to the Contents option and change Access: No access to Access: Read and write. This will allow Quartz Syncer to manage your Quartz’ content folder.
7. Now scroll down and click the button that says Generate token.
8. A popup with show with the current settings. Click Generate token to confirm.
9. Click the copy button to copy the generated access token.
10. Open Obsidian.
11. Open Obsidian’s settings and click on Quartz Syncer under Community Plugins.
12. Paste the generated token in the GitHub token field.

Set up Quartz Syncer

In Obsidian, open Settings > Community Plugins > Quartz Syncer > Options and configure the following fields:

• GitHub repo name: the name of your repository on GitHub.
• GitHub username: the name of the GitHub user (or organization) the repository belongs to.
• GitHub token: the generated authentication token to allow Quartz Syncer to manage your Quartz content folder.

Configuration Example

Using the original Quartz repository as an example:

The repository is hosted at https://github.com/jackyzha0/quartz.

• Repository name: quartz
• Username: jackyzha0
• GitHub token: generated token. usually starts with github_pat_ or ghp_.

After setting all three fields, you should get a green checkmark in the Quartz Syncer options. If not, check the relevant troubleshooting page for help.

That’s it

You should now be able to start publishing to Quartz using Quartz Syncer.

For further details, check the Usage Guide.