Building a Digital Garden with Quartz, Obsidian, and Astro

I’ve been taking digital notes for decades now. From simple .txt files to OneNote, Evernote, Notion, and now Obsidian. But for years, I’ve been wrestling with a question: how do I share my knowledge with others in a way that preserves the connections between ideas?

Enter Quartz - an open-source static site generator designed specifically for transforming Obsidian vaults into interconnected digital gardens. I’ve been using it with Astro to power this very blog, and today I want to show you how you can do the same.

What is a Digital Garden?

Before we dive into the technical stuff, let’s talk about what a digital garden actually is. Unlike traditional blogs organized chronologically, a digital garden is more like… well, a garden! It’s a collection of interconnected notes that grow over time.

Think of each note as a plant. Some are seedlings (early ideas), some are in full bloom (well-developed thoughts), and others might be somewhere in between. The beauty of a digital garden is that it evolves organically, with connections forming between ideas just as they do in our brains.

Why Quartz + Obsidian + Astro?

I settled on this stack after trying numerous solutions, and here’s why:

Obsidian: Provides a fantastic editing experience with bi-directional linking, graph views, and markdown support.
Quartz: Transforms Obsidian vaults into interconnected websites with minimal configuration.
Astro: Adds flexibility for custom layouts, components, and integrations not available in Quartz alone.

It’s a match made in heaven - I get the best note-taking experience with Obsidian, the connection-preserving features of Quartz, and the full power of a modern web framework with Astro.

Setting Up Your Digital Garden

Let’s walk through how to set this up step by step.

Step 1: Install Obsidian and Create a Vault

If you haven’t already, download Obsidian and create a new vault for your digital garden content. I recommend having a separate vault for public content to keep it clean.

Step 2: Set Up Quartz

Quartz is essentially a template for your Obsidian content. Here’s how to get it running:

# Clone the Quartz repository
git clone https://github.com/jackyzha0/quartz.git
cd quartz

# Install dependencies
npm install

# Copy your Obsidian vault content to the content folder
# (or symlink it, which is what I do)
ln -s /path/to/your/obsidian/vault content

Once installed, you can customize your Quartz configuration in the quartz.config.ts file. Here’s a snippet of mine:

// quartz.config.ts
const config: QuartzConfig = {
  configuration: {
    pageTitle: "ArgoBox Digital Garden",
    enableSPA: true,
    enablePopovers: true,
    analytics: {
      provider: "plausible",
    },
    baseUrl: "blog.ArgoBox.com",
    ignorePatterns: ["private", "templates", ".obsidian"],
    theme: {
      typography: {
        header: "Space Grotesk",
        body: "Space Grotesk",
        code: "JetBrains Mono",
      },
      colors: {
        lightMode: {
          light: "#fafafa",
          lightgray: "#e5e5e5",
          gray: "#b8b8b8",
          darkgray: "#4e4e4e",
          dark: "#2b2b2b",
          secondary: "#284b63",
          tertiary: "#84a59d",
          highlight: "rgba(143, 159, 169, 0.15)",
        },
        darkMode: {
          light: "#050a18",
          lightgray: "#0f172a",
          gray: "#1e293b",
          darkgray: "#94a3b8",
          dark: "#e2e8f0",
          secondary: "#06b6d4",
          tertiary: "#3b82f6",
          highlight: "rgba(6, 182, 212, 0.15)",
        },
      },
    },
  },
  plugins: {
    transformers: [
      // plugins here
    ],
    filters: [
      // filters here
    ],
    emitters: [
      // emitters here
    ],
  }
};

Step 3: Integrating with Astro

Now, where Quartz ends and Astro begins is where the magic really happens. Here’s how I integrated them:

Create a new Astro project:

npm create astro@latest my-digital-garden
cd my-digital-garden

Set up your Astro project structure:

my-digital-garden/
├── public/
├── src/
│   ├── components/
│   ├── layouts/
│   ├── pages/
│   │   └── index.astro
│   └── content/ (this will point to your Quartz content)
├── astro.config.mjs
└── package.json

Configure Astro to work with Quartz’s output:

// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  integrations: [
    // Your integrations here
  ],
  markdown: {
    remarkPlugins: [
      // The same remark plugins used in Quartz
    ],
    rehypePlugins: [
      // The same rehype plugins used in Quartz
    ]
  }
});

Create a component for the Obsidian graph view (similar to what I use on this blog):

---
// Graph.astro
---

<div class="graph-container">
  <div class="graph-visualization">
    <div class="graph-overlay"></div>
    <div class="graph-nodes" id="obsidian-graph"></div>
  </div>
  <div class="graph-caption">Interactive visualization of interconnected notes</div>
</div>

<script src="/blog/scripts/neural-network.js" defer></script>

<style>
  .graph-container {
    width: 100%;
    height: 400px;
    position: relative;
    border-radius: 0.75rem;
    overflow: hidden;
    background: rgba(15, 23, 42, 0.6);
    border: 1px solid rgba(56, 189, 248, 0.2);
  }
  
  .graph-visualization {
    width: 100%;
    height: 100%;
    position: relative;
  }
  
  .graph-overlay {
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    background: radial-gradient(
      circle at center,
      transparent 0%,
      rgba(15, 23, 42, 0.5) 100%
    );
    z-index: 1;
    pointer-events: none;
  }
  
  .graph-nodes {
    width: 100%;
    height: 100%;
    position: relative;
    z-index: 2;
  }
  
  .graph-caption {
    position: absolute;
    bottom: 0.75rem;
    left: 0;
    width: 100%;
    text-align: center;
    color: rgba(148, 163, 184, 0.8);
    font-size: 0.875rem;
    z-index: 3;
  }
</style>

Writing Content for Your Digital Garden

Now that you have the technical setup, let’s talk about how to structure your content. Here’s how I approach it:

1. Use Meaningful Frontmatter

Each note should have frontmatter that helps organize and categorize it:

---
title: "Building a Digital Garden"
description: "How to create a connected knowledge base with Obsidian and Quartz"
pubDate: 2023-11-05
updatedDate: 2024-02-10
category: "Knowledge Management"
tags: ["digital-garden", "obsidian", "quartz", "notes"]
---

2. Create Meaningful Connections

The power of a digital garden comes from connections. Use Obsidian’s [[wiki-links]] liberally to connect related concepts:

I'm using the [[quartz-digital-garden|Quartz framework]] to power my digital garden. It works well with [[obsidian-setup|my Obsidian workflow]].

3. Use Consistent Structure for Your Notes

I follow a template for most of my notes to maintain consistency:

Brief introduction/definition
Why it matters
Key concepts
Examples or code snippets
References to related notes
External resources

4. Leverage Obsidian Features

Make use of Obsidian’s unique features that Quartz preserves:

Callouts for highlighting important information
Dataview for creating dynamic content (if using the Dataview plugin)
Graphs to visualize connections

Deploying Your Digital Garden

Here’s how I deploy my digital garden to Cloudflare Pages:

Build Configuration:

// Build command
astro build

// Output directory
dist

Automated Deployment from Git:

I have a GitHub action that publishes my content whenever I push changes:

name: Deploy to Cloudflare Pages

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - name: Install Dependencies
        run: npm ci
      - name: Build
        run: npm run build
      - name: Deploy to Cloudflare Pages
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          projectName: digital-garden
          directory: dist

My Digital Garden Workflow

Here’s my actual workflow for maintaining my digital garden:

Daily note-taking in Obsidian (private vault)
Weekly review where I refine notes and connections
Publishing prep where I move polished notes to my public vault
Git commit and push which triggers the deployment

The beauty of this system is that my private thinking and public sharing use the same tools and formats, reducing friction between capturing thoughts and sharing them.

Adding Interactive Elements

One of my favorite parts of using Astro with Quartz is that I can add interactive elements to my digital garden. For example, the neural graph visualization you see on this blog:

// Simplified version of the neural network graph code
document.addEventListener('DOMContentLoaded', () => {
  const container = document.querySelector('.graph-nodes');
  if (!container) return;
  
  // Configuration
  const CONNECTION_DISTANCE = 30;
  const MIN_NODE_SIZE = 4;
  const MAX_NODE_SIZE = 12;
  
  // Fetch blog data from the same origin
  async function fetchQuartzData() {
    // In production, fetch from your actual API
    return {
      nodes: [
        {
          id: 'digital-garden',
          title: 'Digital Garden',
          tags: ['knowledge-management', 'notes'],
          category: 'concept'
        },
        // More nodes here
      ],
      links: [
        { source: 'digital-garden', target: 'obsidian' },
        // More links here
      ]
    };
  }
  
  // Create the visualization
  fetchQuartzData().then(graphData => {
    // Create nodes and connections
    // (implementation details omitted for brevity)
  });
});

Tips for a Successful Digital Garden

After maintaining my digital garden for over a year, here are my top tips:

Start small - Begin with a few well-connected notes rather than trying to publish everything at once.
Focus on connections - The value is in the links between notes, not just the notes themselves.
Embrace imperfection - Digital gardens are meant to grow and evolve; they’re never “finished.”
Build in public - Share your process and learnings as you go.
Use consistent formatting - Makes it easier for readers to navigate your garden.

The Impact of My Digital Garden

Since starting my digital garden, I’ve experienced several unexpected benefits:

Clearer thinking - Writing for an audience forces me to clarify my thoughts.
Unexpected connections - I’ve discovered relationships between ideas I hadn’t noticed before.
Community building - I’ve connected with others interested in the same topics.
Learning accountability - Publishing regularly motivates me to keep learning.

Wrapping Up

Building a digital garden with Quartz, Obsidian, and Astro has transformed how I learn and share knowledge. It’s become so much more than a blog - it’s a living representation of my thinking that grows more valuable with each connection I make.

If you’re considering starting your own digital garden, I hope this guide gives you a solid foundation. Remember, the best garden is the one you actually tend to, so start simple and let it grow naturally over time.

What about you? Are you maintaining a digital garden or thinking about starting one? I’d love to hear about your experience in the comments!

This post was last updated on February 10, 2024 with information about the latest Quartz configuration options and integration with Astro.

Post Connections

Knowledge Graph

Node Info

Type: Post

Category: Category

Tags:

Content Preview:

Select a post to view content preview

Connections:

View Content