Obsidian and Quartz

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.