416 lines
12 KiB
Markdown
416 lines
12 KiB
Markdown
---
|
|
title: Building a Digital Garden with Quartz, Obsidian, and Astro
|
|
description: How to transform your Obsidian notes into a beautiful, connected public digital garden using Quartz and Astro
|
|
pubDate: 2025-04-18
|
|
updatedDate: 2025-04-19
|
|
category: Services
|
|
tags:
|
|
- quartz
|
|
- obsidian
|
|
- digital-garden
|
|
- knowledge-management
|
|
- astro
|
|
heroImage: /images/posts/prometheusk8.png
|
|
---
|
|
|
|
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](https://quartz.jzhao.xyz/) - 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](https://obsidian.md/) 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```typescript
|
|
// quartz.config.ts
|
|
const config: QuartzConfig = {
|
|
configuration: {
|
|
pageTitle: "LaForceIT Digital Garden",
|
|
enableSPA: true,
|
|
enablePopovers: true,
|
|
analytics: {
|
|
provider: "plausible",
|
|
},
|
|
baseUrl: "blog.laforceit.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:
|
|
|
|
1. Create a new Astro project:
|
|
|
|
```bash
|
|
npm create astro@latest my-digital-garden
|
|
cd my-digital-garden
|
|
```
|
|
|
|
2. 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
|
|
```
|
|
|
|
3. Configure Astro to work with Quartz's output:
|
|
|
|
```typescript
|
|
// 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
|
|
]
|
|
}
|
|
});
|
|
```
|
|
|
|
4. Create a component for the Obsidian graph view (similar to what I use on this blog):
|
|
|
|
```astro
|
|
---
|
|
// 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:
|
|
|
|
```markdown
|
|
---
|
|
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:
|
|
|
|
```markdown
|
|
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:
|
|
|
|
1. **Build Configuration**:
|
|
|
|
```javascript
|
|
// Build command
|
|
astro build
|
|
|
|
// Output directory
|
|
dist
|
|
```
|
|
|
|
2. **Automated Deployment from Git**:
|
|
|
|
I have a GitHub action that publishes my content whenever I push changes:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
1. **Daily note-taking** in Obsidian (private vault)
|
|
2. **Weekly review** where I refine notes and connections
|
|
3. **Publishing prep** where I move polished notes to my public vault
|
|
4. **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:
|
|
|
|
```javascript
|
|
// 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:
|
|
|
|
1. **Start small** - Begin with a few well-connected notes rather than trying to publish everything at once.
|
|
|
|
2. **Focus on connections** - The value is in the links between notes, not just the notes themselves.
|
|
|
|
3. **Embrace imperfection** - Digital gardens are meant to grow and evolve; they're never "finished."
|
|
|
|
4. **Build in public** - Share your process and learnings as you go.
|
|
|
|
5. **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._ |