My Notes

Quartz course

9 min read

Comprehensive Guide to Quartz for Obsidian

Table of Contents

  1. Introduction to Quartz
  2. Setting Up Quartz
  3. Basic Configuration
  4. Content Management
  5. Customizing Your Site
  6. Advanced Features
  7. Deployment and Hosting
  8. Troubleshooting
  9. Quartz 5 Specifics
  10. Additional Resources

Introduction to Quartz

What is Quartz?

Quartz is an open-source publishing system designed specifically for Obsidian users who want to share their knowledge bases online. It transforms your Obsidian vault into a beautiful, interconnected website while preserving the features that make Obsidian powerful:

  • Network of interlinked notes
  • Backlinks
  • Graph views
  • Search functionality
  • Markdown formatting

Why Use Quartz?

  • Preserve Your Knowledge Structure: Maintain the same network of thoughts online that you have in Obsidian
  • Free and Open Source: No subscription fees or proprietary limitations
  • Customizable: Extensive options for personalization
  • Modern Web Features: Fast loading, responsive design, dark/light mode
  • Privacy Control: Choose exactly which notes to publish

Quartz vs. Alternatives

FeatureQuartzObsidian PublishJekyll/Hugo
CostFreePaid subscriptionFree
Learning CurveModerateEasySteep
CustomizationExtensiveLimitedExtensive
Automatic UpdatesManualAutomaticManual
Integration with ObsidianNativeNativeRequires setup

Setting Up Quartz

Prerequisites

Before starting, ensure you have:

  • Node.js (v18.14.0 or higher)
  • git installed on your computer
  • A GitHub account (for deployment via GitHub Pages)
  • Basic familiarity with terminal/command line
  • Your Obsidian vault

Installation Steps

  1. Clone the Quartz repository:

    git clone https://github.com/jackyzha0/quartz.git
cd quartz

  2. Install dependencies:

    npm install

  3. Copy your Obsidian content:

    • Copy your .md files from your Obsidian vault to the content folder in your Quartz directory
    • Alternatively, you can set up a symlink for automatic syncing

  4. Initialize the site:

    npx quartz build

  5. Preview your site locally:

    npx quartz serve

    This will start a local development server, typically at http://localhost:8080

Directory Structure

Understanding the Quartz directory structure is important:

quartz/
├── content/            # Your Markdown files go here
├── public/             # Static assets (images, etc.)
├── quartz/             # Quartz core files
│   ├── components/     # UI components
│   ├── plugins/        # Functionality plugins
│   ├── styles/         # CSS styling
│   └── ...
├── .github/            # GitHub workflows for deployment
├── .gitignore          # Git ignore file
├── package.json        # Project dependencies
├── quartz.config.ts    # Main configuration file
└── README.md           # Documentation

Basic Configuration

The Configuration File

The main configuration is handled through quartz.config.ts. This TypeScript file defines how your site looks and behaves.

Essential Settings

const config: QuartzConfig = {
  configuration: {
    // Site metadata
    pageTitle: "My Digital Garden",    // Title in browser tabs
    enableSPA: true,                   // Single Page Application mode
    enablePopovers: true,              // Preview on hover
    analytics: { provider: "none" },   // Analytics settings
    
    // Content settings
    baseUrl: "example.com",            // Your domain name
    ignorePatterns: ["private", "templates", ".obsidian"], // Excluded folders
    defaultDateType: "created",        // Sort by created or modified date
    
    // Theme settings
    theme: {
      typography: {
        header: "Schibsted Grotesk",   // Header font
        body: "Source Sans Pro",       // Body font
        code: "IBM Plex Mono",         // Code block font
      },
      colors: {
        // Color scheme settings
        // ...
      }
    }
  },
  
  // Plugins configuration
  plugins: {
    // ...
  }
}

Common Configuration Tasks

Changing Site Title

pageTitle: "Your Site Name",
pageTitleSuffix: " - Optional Suffix",

Excluding Private Notes

ignorePatterns: [
  "private",
  "templates",
  ".obsidian",
  "journal/daily", 
  "personal"
],

Setting Up Analytics

analytics: {
  provider: "google",
  googleAnalyticsId: "G-XXXXXXXXXX",
},
// Or
analytics: {
  provider: "plausible",
  plausibleDataDomain: "yourdomain.com",
},

Changing Date Display

defaultDateType: "created", // or "modified"

Content Management

Organizing Your Content

Quartz will maintain your existing folder structure from Obsidian. Some best practices include:

  • Keep a logical folder structure that makes navigation intuitive
  • Use an index.md file in each folder to serve as a landing page
  • Consider a homepage at the root level (content/index.md)

Frontmatter

Quartz recognizes YAML frontmatter for additional metadata:

---
title: Note Title
description: Brief description for SEO
date: 2023-04-15
tags:
  - example
  - notes
draft: true  # Won't be published if draft is true
---

Key frontmatter fields:

  • title: Overrides the filename as the displayed title
  • description: Used for SEO and preview snippets
  • date: Publication or creation date
  • tags: Categories for your note
  • draft: Set to true to exclude from publishing
  • aliases: Alternative names for linking

Linking Between Notes

Quartz preserves Obsidian’s double-bracket link syntax:

  • [[Note Name]] - Creates a link to the note
  • [[Note Name|Display Text]] - Creates a link with custom display text

Quartz will attempt to resolve these links automatically.

Working with Images and Assets

For images and other media:

  1. Place images in the content directory (preferably in a specific subfolder like content/assets/)

  2. Reference them in your notes using standard Markdown:

    ![Image Description](assets/image.png)

  3. For Obsidian attachments, maintain the same relative paths

Tags and Metadata

Tags work just like in Obsidian:

  • Use YAML frontmatter for organized tags:

    tags:  - productivity  - notes

  • Or use inline tags in your content with #tag-name

Quartz automatically generates tag pages and provides filtering capabilities.

Customizing Your Site

Theming Basics

Changing Fonts

Modify the typography section in your configuration:

theme: {
  fontOrigin: "googleFonts", // or "local"
  typography: {
    header: "Playfair Display",
    body: "Inter",
    code: "JetBrains Mono",
  }
}

Color Schemes

Customize colors for both light and dark modes:

colors: {
  lightMode: {
    light: "#faf8f8",       // Background
    lightgray: "#e5e5e5",   // Dividers
    gray: "#b8b8b8",        // Muted text
    darkgray: "#4e4e4e",    // Secondary text
    dark: "#2b2b2b",        // Primary text
    secondary: "#284b63",   // Links
    tertiary: "#84a59d",    // Accents
    highlight: "rgba(143, 159, 169, 0.15)", // Highlighted background
  },
  darkMode: {
    // Dark mode equivalents
    // ...
  }
}

CSS Customization

For more advanced customization, you can add custom CSS:

  1. Create a file in quartz/styles/custom.scss

  2. Add your custom CSS rules:

    // Example custom styles.note-title {  font-size: 2.5rem;  font-weight: 700;}.callout {  border-radius: 10px;  border-width: 2px;}

Customizing Components

For deeper customization, you can modify the components:

  1. Find the component you want to modify in quartz/components/
  2. Create a copy with your changes
  3. Import and use your custom component in the appropriate plugin

Plugin Customization

Quartz has a plugin system for extensibility:

plugins: {
  transformers: [
    Plugin.FrontMatter(),
    Plugin.CreatedModifiedDate({
      priority: ["frontmatter", "git", "filesystem"],
    }),
    // Other transformers
  ],
  filters: [
    Plugin.RemoveDrafts(),
    // Custom filters
  ],
  emitters: [
    Plugin.ContentPage(),
    Plugin.FolderPage(),
    Plugin.TagPage(),
    // Other emitters
  ],
}

Common plugin customizations:

  • Adjust syntax highlighting themes
  • Configure table of contents generation
  • Set up LaTeX rendering options

Advanced Features

Graph View

Enable and customize the graph visualization:

Plugin.GraphView({
  localGraph: {
    depth: 1,
    showTags: true,
    showAttachments: true,
  },
  globalGraph: {
    drag: true,
    zoom: true,
    repelForce: 0.5,
  }
}),

Search Functionality

Configure the search capabilities:

Plugin.Search({
  enablePreview: true,
  enableSemanticSearch: false,
}),

Custom Layouts

Create different layouts for different types of content:

  1. Define layout templates in quartz/components/
  2. Configure which layouts apply to which content in your plugins

Callouts and Admonitions

Quartz supports Obsidian-style callouts:

> [!note] Note Title
> 
> This is a note callout
 
> [!warning] Warning
> 
> This is a warning callout

You can customize the appearance of these callouts via CSS.

Custom JavaScript

Add custom JavaScript functionality:

  1. Create a file in quartz/components/scripts/
  2. Import and use it in your configuration

Deployment and Hosting

GitHub Pages Deployment

The easiest deployment method is using GitHub Pages:

  1. Push your Quartz repository to GitHub
  2. Enable GitHub Pages in your repository settings
  3. Configure GitHub Actions workflow (already included in Quartz)

Basic steps:

# Initialize git
git init
 
# Add your files
git add .
 
# Commit changes
git commit -m "Initial Quartz setup"
 
# Add remote GitHub repository
git remote add origin https://github.com/yourusername/your-repo-name.git
 
# Push to GitHub
git push -u origin main

Netlify Deployment

For Netlify hosting:

  1. Push your repo to GitHub
  2. Connect Netlify to your GitHub repository
  3. Configure build settings:
    • Build command: npx quartz build
    • Publish directory: public

Custom Domain Setup

To use a custom domain:

  1. Purchase a domain from a registrar
  2. Update the baseUrl in your Quartz config
  3. Configure DNS settings at your registrar:
    • For GitHub Pages: Create CNAME records pointing to your GitHub Pages URL
    • For Netlify: Follow Netlify’s domain configuration

Automated Deployments

Set up automatic rebuilds when your Obsidian vault changes:

  1. Use GitHub Actions for automated builds
  2. Configure triggers based on content changes
  3. Set up a workflow that rebuilds on push or scheduled intervals

Troubleshooting

Common Issues and Solutions

Issue: Some internal links aren’t working Solution: Check for:

  • Case sensitivity issues in filenames
  • Special characters in filenames
  • Missing files that are being linked to

Styling Problems

Issue: CSS not applying as expected Solution:

  • Clear browser cache
  • Check for CSS syntax errors
  • Verify that your custom CSS is being loaded

Build Errors

Issue: npx quartz build fails Solution: Check for:

  • Node.js version compatibility
  • Missing dependencies
  • Invalid configuration in quartz.config.ts
  • Syntax errors in your content files

Performance Issues

Issue: Site loads slowly Solution:

  • Reduce the number of embedded images
  • Optimize large graph views
  • Remove unnecessary plugins
  • Enable caching options

Debugging Tools

  • Use browser dev tools to inspect elements and CSS
  • Check the terminal output during build for errors
  • Enable verbose logging in Quartz config

Quartz 5 Specifics

What’s New in Quartz 5

Quartz 5 introduces several improvements and new features:

  • Enhanced performance and build times
  • Improved mobile responsiveness
  • New plugin architecture
  • Better SEO optimization
  • Additional customization options

Migrating from Quartz 4

If upgrading from Quartz 4:

  1. Backup your content and custom configurations
  2. Clone the new Quartz 5 repository
  3. Transfer your content to the new installation
  4. Update your configuration file:
    • Note changes in plugin naming and structure
    • Review new configuration options
    • Port over custom styles and components

New Configuration Options

// Quartz 5 specific configuration options
const config: QuartzConfig = {
  configuration: {
    // New options in Quartz 5
    enablePagePreview: true,     // Enhanced page previews
    enableGlobalGraph: true,     // Global graph visualization
    searchFeatures: {
      enableFuzzySearch: true,   // Improved search functionality
      enableFilterByTags: true,  // Filter search results by tags
    },
    // ...
  }
}

New Component Architecture

Quartz 5 uses a more modular component system:

// Example of new component usage
import { Component } from "./quartz/components/types"
import MyCustomComponent from "./components/MyCustomComponent"
 
// Register custom component
const components: Component[] = [
  MyCustomComponent(),
  // Other components
]

Additional Resources

Official Documentation

Community Resources

Helpful Plugins and Extensions

  • Custom Quartz plugins for specific functionality
  • Obsidian plugins that enhance Quartz compatibility
  • Community-created themes and templates

Here are some exemplary Quartz sites to inspire your own:

This guide serves as a comprehensive introduction to Quartz for Obsidian. As Quartz continues to evolve, some specifics may change. Always refer to the official documentation for the most up-to-date information.

Graph View