Digital Garden with Obsidian and Astro

2024-07-11 (updated 2024-07-21) Eiko Wagenknecht

I have been thinking about creating a digital garden for a while now, in addition to my regular blog(s). I enjoy the idea of a public place to collect notes, ideas, and resources that are interconnected and grow over time.

The concept of a digital garden is not new and it has gained popularity in recent years. So there are already tools and platforms available to help set up your own digital garden.

But I wanted to build my own, with full control over the content and design. And since I am using Astro for my blog, I thought it would be a good idea to use Astro for my digital garden as well.

Table of Contents

• Current Tools
• What do we need?
  • Obsidian Flavored Markdown
  • Minimal Theme features
  • Additional features
• Guides

Current Tools

Before we start, let’s take a look at the currently available tools and platforms for digital gardens. I’m using Obsidian for my personal notes, so I’ll focus on tools that can be integrated with it.

• Obsidian Publish
  • The official publishing platform for Obsidian. It’s a great way to publish your notes online, but it’s not very customizable. Also it’s not free.
• Lazy man’s Obsidian + Astro integration
  • A Reddit post with a workflow to integrate Obsidian with Astro. The idea is to create a symlink from your Obsidian vault to your Astro projects content and assets folders. The followup video shows how to use QuickAdd to create content templates.
• obsidian-enveloppe
  • A plugin for Obsidian that converts obsidian notes (with wikilinks, dataviewjs etc.) to plain markdown files and then uploads them to GitHub. Doesn’t support any other workflows and uses Quartz for it’s own website.
• Obsidian-to-Astro
  • A short guide on how to use Obsidian notes in Astro. It’s a manual process and doesn’t support many features.
• Quartz
  • A complete “digital garden” static site generator built for Obsidian, with features like wikilinks, backlinks, latex, syntax highlighting, search, graph view and more. It’s really good for what it aims to be, but it’s not customizable like Astro and not really suitable for a website that also hosts other content.
• Astro Digital Garden
  • A collection of recipes and tips on how to build a digital garden with Astro. It seems to be a work in progress. A good part of the features relies on the BrainDB, which is unfortunately not really documented.

These are good starting points, but I wanted a digital garden as feature rich as Quartz, but with the flexibility of Astro. So I decided to build my own.

What do we need?

A digital garden is essentially a collection of notes, which are interconnected in some way. So we need a way to create and link notes, and a way to display them.

I want to use Obsidian for creating and linking notes, and Astro for displaying them. So we either need a way to convert Obsidian notes to markdown files that Astro can read, or a way to read Obsidian notes directly from Astro. I’m going with the second option, because that way the notes can be directly edited in Obsidian and published without further steps.

I want to have the following features in my digital garden:

Obsidian Flavored Markdown

Obsidian uses it’s own Markdown flavour, which is based on GitHub Flavored Markdown (GFM)¹, and adds some custom extensions. Luckily, Astro already by default supports GFM with remark-gfm, so we only have to add support for the custom extensions:

• Wikilinks ([[wikilink]])
• Embedded files (![[file]])
• Block references (![[block^id]]) and block identifiers (^id)
• Comments (%% comment %%)
• Highlights (==highlight==)
• Callouts (> [!note])
• Task lists (- [ ], - [x]) are presented as strikethrough and checkboxes
• Inline LaTeX
• Mermaid diagrams

Minimal Theme features

Technically not part of Obsidian Flavored Markdown, the minimal theme is very popular and created by a (now) member of the Obsidian team. It adds some additional features that I want to support as well:

• Alternative checkboxes ([/], [-])
• Helper classes for image grids and cards
• Image filters

When all is done, the whole Markdown Test page should be displayed correctly.

Additional features

• Automatic table of contents
• Display of all backlinks
• Display of tags
• Menu with folder structure
• Folder and tag pages
• Search
• Graph view
• Checking for broken links
• Automatic marking of external links

Guides

For now, I have the following guides:

• How to add Obsidian style callouts to Astro

Footnotes

1. GitHub Flavored Markdown itself is a superset of CommonMark, so we need to support this as well. ↩