Obsidian and Quartz

Fri, 10 Jul 2026 10:23:44 +0200

Warning: I am a heavily invested Obsidian user. I am using Obsidian to interact with wikis, websites, this blog, databases and the file system. Most of my vaults are published to the web. To do so I am using Vuepress for most projects. In this blog I am exploring publishing with Quartz.

Vuepress does not know about Obsidian. To some degree this is good. It makes sure that the two systems are decoupled.

Preprocess for Vuepress

However, in order to publish the content of an Obsidian vault with Vuepress I had to to solve many problems:

Convert Wiki-Links to Markdown-Links
Rename attachment files
Generate .svg from .canvas
Generate a sitemap.xml
Append backlinks to markdown files
Append edit link to markdown files
Build a glossary of all file titles
Generate output of .bases
Prepend frontmatter metadata

The most prominent project is the Wiki Mint System. The build.js prepares the content for Vuepress.

Checking out Quartz

The promise of Quartz is that Obsidian is a first citizen. Quartz supports publishing an Obsidian vault and completes Obsidian plugins with its own plugins.

I want to walk you through my trial of publishing the Wiki Mint System with Quartz.

It took my some time to understand that Quartz is not a standalone cli tool. It cannot simply installed, instead you clone the Quartz repo and integrate your content into the repo. Here are the commands to scaffold a new project:

cd ~
git clone https://github.com/jackyzha0/quartz.git
cd quartz
npm i
npx quartz create

The last command starts a wizard. I answered as followed:

Choose a template for your Quartz configuration: Obsidian
Choose how to initialize the content in /home/janikvonrotz/quartz/content: Copy an existing folder
Enter the full path to existing content folder: /home/janikvonrotz/Wiki
Enter the base URL for your Quartz site: wiki.mint-system.ch

Then the Quartz started installing plugins:

Found 45 uninstalled plugin(s) in config:

  created-modified-date — github:quartz-community/created-modified-date
  syntax-highlighting — github:quartz-community/syntax-highlighting
  obsidian-flavored-markdown — github:quartz-community/obsidian-flavored-markdown
  github-flavored-markdown — github:quartz-community/github-flavored-markdown
  table-of-contents — github:quartz-community/table-of-contents
  crawl-links — github:quartz-community/crawl-links
  description — github:quartz-community/description
  latex — github:quartz-community/latex
  citations — github:quartz-community/citations
  hard-line-breaks — github:quartz-community/hard-line-breaks
  ox-hugo — github:quartz-community/ox-hugo
  roam — github:quartz-community/roam
  remove-draft — github:quartz-community/remove-draft
  explicit-publish — github:quartz-community/explicit-publish
  unlisted-pages — github:quartz-community/unlisted-pages
  encrypted-pages — github:quartz-community/encrypted-pages
  stacked-pages — github:quartz-community/stacked-pages
  alias-redirects — github:quartz-community/alias-redirects
  content-index — github:quartz-community/content-index
  favicon — github:quartz-community/favicon
  og-image — github:quartz-community/og-image
  cname — github:quartz-community/cname
  canvas-page — github:quartz-community/canvas-page
  content-page — github:quartz-community/content-page
  folder-page — github:quartz-community/folder-page
  tag-page — github:quartz-community/tag-page
  explorer — github:quartz-community/explorer
  graph — github:quartz-community/graph
  search — github:quartz-community/search
  backlinks — github:quartz-community/backlinks
  article-title — github:quartz-community/article-title
  content-meta — github:quartz-community/content-meta
  tag-list — github:quartz-community/tag-list
  page-title — github:quartz-community/page-title
  darkmode — github:quartz-community/darkmode
  reader-mode — github:quartz-community/reader-mode
  breadcrumbs — github:quartz-community/breadcrumbs
  comments — github:quartz-community/comments
  footer — github:quartz-community/footer
  recent-notes — github:quartz-community/recent-notes
  spacer — github:quartz-community/spacer
  bases-page — github:quartz-community/bases-page
  note-properties — github:quartz-community/note-properties
  quartz-themes — github:saberzero1/quartz-themes (subdir: plugin)
  obsidian-plugin-excalidraw — github:quartz-community/obsidian-plugin-excalidraw

Uff, that is quite a a lot.

Next and final step of the process is starting building the Quartz site.

npx quartz build --serve

I expected things to just work. But, I ran into some problems:

Failed to process html `content/Kreis Infrastruktur.md`: URI malformed
     at decodeURI (<anonymous>)
     at file:///home/janikvonrotz/quartz/.quartz/plugins/crawl-links/src/transformer.ts:122:49

There were non supported characters in filenames:

- [[Rolle Systemadministrator%in]]

Once I resolved this I ran into the next problem:

Multiple source files produced the same URL slug. The last-processed file wins; the others are shadowed and their content will not appear in the output.

  slug `docker`
    - Docker.md (shadowed)
    - docker.md (used for this URL)

  slug `git`
    - Git.md (shadowed)
    - git.md (used for this URL)

  slug `mail-hosting`
    - Mail Hosting.md (shadowed)
    - Mail-Hosting.md (used for this URL)

To resolve, rename or delete all but one file per collided slug. This may include files using the Obsidian "Folder Notes" convention (`folder/folder.md`) that collide with an existing `folder/index.md`.

Some names collided with other documents are reserved names. I had to rename these files as well.

And voila: http://localhost:8080/readme

I am aware that this is localhost link. Instead of showing you what the result looks like I give you a list of many problems with my test:

The font family is not set
Edit links are missing
The explorer shows all files including attachments and bases folders
The backlinks shows all bases
As expected the [[TOC]] and ::: blocks are not rendered
Some documents like uri-cloud does not work
Frontmatter data is not shown
Some documents with - in the title cannot be opened, f.g. richtlinie---informationssicherheit

But other parts worke quite well and many things I missed in Vuepress are supported by Quartz:

Graph view on the top right
Bases view are generated
Full-text search
Canvas view is generated including links
Hovering on a wiki links shows a preview
Header anchor links are shown
Mermaid diagrams are rendered

Summary

Simply switching from Vuepress to Quartz is not that easy. Quartz takes a whole different approach on how the integration and publishing process works. It is a real bother that Quartz cannot be run without using the repo.

I will keep an eye on the project and will most likely use it for publishing a new Obsidian vault.

Vuepress on Janik von Rotz

Obsidian and Quartz

Preprocess for Vuepress

Checking out Quartz

Summary