This Digital Garden is built with Obsidian and Quartz which is a static site generator built specifically for converting Obsidian vaults into websites.
I have a private repository notes.hamatti.org
that starts with a clone of the Quartz repository and then adds my own configuration on top.
Building
I don’t want to store my Obsidian vault inside the tooling, so I have set up a build & development server scripts inside package.json
:
"scripts" {
"build": "npx quartz build --directory=/path/to/my/Obsidian/vault",
"serve": "npx quartz build --serve --port 8888 --directory=/path/to/my/Obsidian/vault"
}
When I want to update my digital garden, I run a build, add changes to git and push it to GitHub from where it gets automatically picked up by my hosting and built into a new version and published.
This requires manual building and publishing but like with my main website, I like that manual step and in case of publishing a public subset of private notes, I want to be able to manually check that I haven’t accidentally put a note into a wrong folder from where it would be picked up by automation to publish on the web.
External links
For digital gardens, I think it’s nice to visually indicate which links are internal links and which one lead to elsewhere. Quartz provides this as a configuration option for its CrawlLinks
plugin but I turn that off and instead, I use CSS ::after
pseudo-element. My main reason for this is to avoid the SVGs from showing up wonky in different RSS readers.
Internal links to missing pages
In Obsidian, I create links to other notes before I make those notes. Sometimes I make those notes right away, sometimes they are there to let me know through autocomplete that I’ve written about it before.
On a published site, those would all lead to 404 for missing note and that’s not a great UX.
There’s currently no way to configure this in Quartz but thanks to it being open source and people contributing, I found help in the GitHub issues. In contentPage.tsx
, inside the emit
method, inside the for (const [tree, file] of content)
loop, I added
and added the missing imports. This changes the missing links from a
tags to span
tags, saving the end user from confusion and unnecessary navigation to 404 page.
Thoughts on Quartz
While in general I’m happy with the ease of use and the ability to configure things by changing the source code of Quartz, one thing that bothers me is the extensive use of client-side Javascript.
There’s a lot of inlined Javascript I haven’t yet been able to clean up and a lot of that causes git to be super slow because there each content change introduces changes into the inlined Javascript so calculating diffs becomes a chore to the computer.
On each individual page, there are thousands of incredibly long lines of inlined Javascript and CSS and I can’t figure out why or how I can get rid of them. A static site does not need this much extra weight.
As an experiment, in renderPage.tsx
, I commented out contentIndexScript
and staticResources.js
. This seems to have removed a good few thousand lines of content and so far the only non-working part I could find was search which I removed gladly.
What if I can’t or don’t want to code?
Maggie Appleton has a great guide at Digital Gardening for Non-Technical Folks