Quartz + GitHub Pages: turning Obsidian notes into a digital garden

A video about setting up Obsidian Publish is coming soon on the channel; for now you can read the article on how to set it up:

Introduction: from notes to a digital garden

Imagine you have a collection of hundreds of notes in Obsidian — your personal knowledge archive that’s been accumulating for months or years. These notes are connected, contain valuable insights and could benefit not only you, but other people too.

The problem is that they’re locked in your app and unavailable to the world. Quartz solves this problem by turning your notes into a full-fledged website — your own digital garden.

What is a digital garden?

A digital garden is a concept of publishing knowledge that’s fundamentally different from a traditional blog:

A blog is a chronological feed of finished articles
A digital garden is a living space for growing ideas

In a digital garden your notes can be:

🌱 Seedlings — raw thoughts, drafts
🌿 Budding — ideas in the process of being worked out
🌳 Evergreen — finished notes

This concept removes the pressure of perfectionism: you can publish unfinished thoughts and refine them publicly.

What Quartz is and why it’s better than the alternatives

Quartz is a static site generator built specifically for working with notes in Markdown format. To put it simply: Quartz takes your files from Obsidian and turns them into a beautiful site with all the links, graph and search.

Quartz’s advantages over other solutions:

Criterion	Obsidian Publish	Notion Sites	Quartz
Cost	$10/month	Free	Free
Wiki-links	✅	❌	✅
Connection graph	✅	❌	✅
Full control	❌	❌	✅
Works in Russia	❌ (Cloudflare)	✅	✅
Speed	⚡⚡	⚡	⚡⚡⚡

Quartz’s technical advantages:

✅ Full compatibility with Obsidian — wiki-links, backlinks, callouts ✅ Static generation — the site works fast and reliably ✅ GitHub Pages — free hosting with global availability ✅ Versioning — the whole history of changes is saved in Git ✅ Independence — your data belongs only to you

What is Quartz Syncer?

Quartz Syncer is a plugin for Obsidian that automates the whole technical side of working with Quartz. Now publishing works as simply as in Obsidian Publish:

Wrote a note in Obsidian
Marked it for publishing via the plugin
Clicked “Sync”
The site updated automatically

Quartz Syncer’s capabilities:

🔄 Automatic synchronisation with the GitHub repository 📝 Publishing right from Obsidian — like in Obsidian Publish 📁 Selective publishing — you can choose specific folders 🔌 Support for Obsidian plugins — Dataview, Templates and others ⚡ On-the-fly compilation — processes dynamic content

This effectively restores the convenience of Obsidian Publish, but with full control and global availability!

Getting ready

The necessary tools

Before you start, make sure you have:

Obsidian with a collection of notes
A GitHub account (create one for free at github.com)
The Quartz Syncer plugin (installed via Community Plugins in Obsidian)

Optional tools for the advanced method:

GitHub Desktop (download) — a graphical interface for Git
Node.js (download) — the runtime for Quartz

🟢 The simple method: via the GitHub web interface

Suitable for: those who want to try Quartz without installing extra programs Setup time: 30-45 minutes Difficulty level: like creating a social-media account

Step 1: Creating a GitHub repository

Open the Quartz template in your browser
Click the green “Use this template” button → “Create a new repository”
Configure the repository:
- Repository name: my-digital-garden (or any other name)
- Description: My digital garden based on Obsidian
- Visibility: Public (required for free GitHub Pages)
Click “Create repository”

Step 2: Activating GitHub Pages

Go to your repository’s Settings
Find the Pages section in the left menu
Choose Source: GitHub Actions (not Deploy from a branch!)
Save the settings

GitHub will automatically start the site-building process. In 5-10 minutes your site will be available at: https://username.github.io/repository-name

Step 3: Installing Quartz Syncer in Obsidian

Open Obsidian → Settings → Community Plugins
Find and install “Quartz Syncer”
Activate the plugin in the list of installed ones

Step 4: Configuring Quartz Syncer

Open the Quartz Syncer plugin settings
Choose “Connect to GitHub”
Follow the instructions for creating a GitHub token:
- Go to GitHub → Settings → Developer settings → Personal access tokens
- Create a new token with rights to your repository
- Copy the token into the plugin settings
Choose your repository from the list
Configure the folders for synchronisation

Step 5: The first publication

Choose 2-3 notes for testing
Make sure they contain quality content and correct links
Click the “Sync” button in the Quartz Syncer plugin
Wait for the synchronisation to finish (1-2 minutes)
Check the site in 5-10 minutes

Advantages of the simple method:

✅ Doesn’t require installing extra programs ✅ All settings via the web interface ✅ Good for quick testing ✅ A minimal barrier to entry

Limitations of the simple method:

❌ Limited design-customisation options ❌ Harder to add your own styles and scripts ❌ No local copy for working offline

🟡 The advanced method: via GitHub Desktop

Suitable for: those who want maximum control and flexibility Setup time: 1-2 hours Difficulty level: like learning a new program such as Photoshop

Step 1: Installing the necessary tools

1.1 GitHub Desktop

Download GitHub Desktop
Install it and log into your GitHub account
Explore the basic interface (5 minutes)

1.2 Node.js

Download the Node.js LTS version
Install it with the default settings
Check the installation via the command line:
```
node --version
npm --version
```

Step 2: Setting up the local project

2.1 Cloning Quartz

Open GitHub Desktop
Click File → Clone repository → URL
Paste https://github.com/jackyzha0/quartz.git
Choose a folder for the project on your computer
Click Clone

2.2 Creating your own repository

Create a new repository on GitHub (as in the simple method)
In GitHub Desktop click Repository → Repository settings
Change the Remote URL to your new repository
Publish the changes: Repository → Push origin

Step 3: Basic Quartz setup

3.1 Installing the dependencies

Open the command line (Terminal/Command Prompt)
Go to the project folder:
```
cd path/to/your/quartz
```
Install the dependencies:
```
npm install
```

3.2 Configuring the setup

Open the quartz.config.ts file in any text editor

Change the main parameters:

const config: QuartzConfig = {  configuration: {    pageTitle: "My digital garden",    enableSPA: true,    enablePopovers: true,    analytics: {      provider: "plausible", // or "google"    },    locale: "en-US",    baseUrl: "https://username.github.io/repository-name",    ignorePatterns: [      "private",      "templates",       ".obsidian",      "drafts"    ],  },}

Step 4: Setting up automatic publishing

4.1 GitHub Actions

Quartz comes with a ready-made configuration in the .github/workflows/deploy.yml file. It automatically:

Builds the site on every push
Publishes via GitHub Pages
Updates the site within 5-10 minutes

4.2 Enabling GitHub Pages

Go to the repository’s Settings on GitHub
Find the Pages section
Choose Source: GitHub Actions
Save the settings

Step 5: Integration with Obsidian via Quartz Syncer

5.1 Configuring the plugin

Install Quartz Syncer in Obsidian
In the plugin settings, choose “Local repository”
Specify the path to the local Quartz folder
Configure the folders for synchronisation

5.2 The publishing workflow

Now the publishing process looks like this:

You write a note in Obsidian
You synchronise it via Quartz Syncer
The plugin automatically copies the files into the content folder
GitHub Desktop shows the changes
You commit and push via GitHub Desktop
GitHub Actions automatically updates the site

Advantages of the advanced method:

✅ Full control over the design and functionality ✅ Local development — you can test changes offline ✅ Customisation — adding your own styles, scripts, plugins ✅ Performance — optimisation for your needs ✅ Backups — a local copy of all the files

Possible difficulties:

❌ Requires installing extra programs ❌ More technical details to learn ❌ Can be overkill for simple tasks

Customising and optimising the site

Configuring the appearance

Basic settings in quartz.config.ts

theme: {
  cdnCaching: true,
  typography: {
    header: "Schibsted Grotesk",
    body: "Source Sans Pro",
    code: "IBM Plex Mono",
  },
  colors: {
    lightMode: {
      light: "#faf8f8",
      lightgray: "#e5e5e5", 
      gray: "#b8b8b8",
      darkgray: "#4e4e4e",
      dark: "#2b2b2b",
      secondary: "#284b63",
      tertiary: "#84a59d",
      highlight: "rgba(143, 159, 169, 0.15)",
    },
    darkMode: {
      light: "#161618",
      lightgray: "#393639",
      gray: "#646464",
      darkgray: "#d4d4d4", 
      dark: "#ebebec",
      secondary: "#7b97aa",
      tertiary: "#84a59d",
      highlight: "rgba(143, 159, 169, 0.15)",
    },
  },
},

Creating custom styles

Create the file quartz/styles/custom.scss

Add your own styles:

// Font settingsbody {  font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;}// Heading stylesh1, h2, h3 {  color: var(--dark);  font-weight: 600;}// Custom callouts.callout[data-callout="tip"] {  border-color: #00d4aa;  background-color: rgba(0, 212, 170, 0.1);}

Configuring the components

The page structure in quartz.layout.ts

export const defaultContentPageLayout: PageLayout = {
  beforeBody: [
    Component.Breadcrumbs(),
    Component.ArticleTitle(),
    Component.ContentMeta(),
    Component.TagList(),
  ],
  left: [
    Component.PageTitle(),
    Component.MobileOnly(Component.Spacer()),
    Component.Search(),
    Component.Darkmode(),
    Component.DesktopOnly(Component.Explorer()),
  ],
  right: [
    Component.DesktopOnly(Component.TableOfContents()),
    Component.Backlinks(),
  ],
}

SEO optimisation

Metadata for notes

Add YAML frontmatter at the start of your notes:

---
title: "The full article title"
description: "A short description for search engines"
tags: ["obsidian", "productivity", "pkm"]
date: 2024-01-15
draft: false
---

Setting up analytics

In quartz.config.ts:

analytics: {
  provider: "google",
  tagId: "G-XXXXXXXXXX", // your Google Analytics ID
},

Best practices for a digital garden

1. Structuring content

Recommended folder structure:

content/
├── index.md                 # Home page
├── about.md                 # About me
├── now.md                   # What I'm doing now
├── notes/                   # Main notes
│   ├── productivity/        # Topic: productivity
│   ├── learning/           # Topic: learning
│   └── tools/              # Topic: tools
├── projects/               # Projects
├── resources/              # Useful resources
└── garden/                 # Growing ideas
    ├── seedlings/          # Idea seeds
    ├── saplings/          # Developing thoughts
    └── evergreens/        # Mature notes

# 🧠 Productivity and knowledge management
 
This is my navigation hub for the topic of productivity.
 
## 🌱 Developing ideas
- [[The Zettelkasten method]]
- [[Second brains]]
- [[Digital minimalism]]
 
## 🌳 Mature concepts  
- [[PARA Method]]
- [[Getting Things Done]]
- [[Principles of effective work with information]]
 
## 🛠 Tools
- [[Obsidian setup]]
- [[Notion vs Obsidian]]
- [[Quartz for publishing]]

2. A system of tags and links

Effective tags:

#seedling — for new, raw ideas
#developing — for ideas in progress
#evergreen — for finished notes
#public — for notes ready to publish
#private — for personal notes (exclude from synchronisation)

Creating links:

Use wiki-links [[Note title]] to create a network of knowledge
Add context [[Note|in the context of the discussion]]
Link to sections [[Note#a-specific-section|A specific section]]

3. The publishing workflow

A weekly update ritual:

Monday: Review the week’s new notes
Wednesday: Develop 2-3 seedling notes
Friday: Publish the updates via Quartz Syncer
Sunday: Analyse the statistics and plan

The process of developing a note:

🌱 Seedling → 🌿 Sapling → 🌳 Evergreen
     ↓            ↓           ↓
Raw idea → Structuring → Publishing
(private)    (adding         (open
              links,          access)
              examples)

4. Interacting with the audience

Adding contact information

Create the file content/contact.md:

# Get in touch with me
 
If these notes were useful or you have questions:
 
- 📧 Email: your@email.com  
- 💬 Telegram: @username
- 🐦 Twitter: @username
- 💼 LinkedIn: /in/username
 
## Feedback is welcome!
 
This digital garden grows thanks to interaction. 
Don't hesitate to share your thoughts and ideas.

Elton Labs

Quartz + GitHub Pages: turning Obsidian notes into a digital garden

Introduction: from notes to a digital garden

What is a digital garden?

What Quartz is and why it’s better than the alternatives

Quartz’s advantages over other solutions:

Quartz’s technical advantages:

What is Quartz Syncer?

Quartz Syncer’s capabilities:

Getting ready

The necessary tools

Optional tools for the advanced method:

🟢 The simple method: via the GitHub web interface

Step 1: Creating a GitHub repository

Step 2: Activating GitHub Pages

Step 3: Installing Quartz Syncer in Obsidian

Step 4: Configuring Quartz Syncer

Step 5: The first publication

Advantages of the simple method:

Limitations of the simple method:

🟡 The advanced method: via GitHub Desktop

Step 1: Installing the necessary tools

1.1 GitHub Desktop

1.2 Node.js

Step 2: Setting up the local project

2.1 Cloning Quartz

2.2 Creating your own repository

Step 3: Basic Quartz setup

3.1 Installing the dependencies

3.2 Configuring the setup

Step 4: Setting up automatic publishing

4.1 GitHub Actions

4.2 Enabling GitHub Pages

Step 5: Integration with Obsidian via Quartz Syncer

5.1 Configuring the plugin

5.2 The publishing workflow

Advantages of the advanced method:

Possible difficulties:

Customising and optimising the site

Configuring the appearance

Basic settings in quartz.config.ts

Creating custom styles

Configuring the components

The page structure in quartz.layout.ts

SEO optimisation

Metadata for notes

Setting up analytics

Best practices for a digital garden

1. Structuring content

Recommended folder structure:

Creating navigation hubs (MOC)

2. A system of tags and links

Effective tags:

Creating links:

3. The publishing workflow

A weekly update ritual:

The process of developing a note:

4. Interacting with the audience

Adding contact information