Building a personal website from Quartz

Some notes on my experience with setting up https://notes.wgslr.com using Quartz, the steps needed to set it up and plans/wishes for the future.

Pros and cons

Some thoughts on what’s nice, what’s missing and what I might want to fix. That’s in comparison to alternative solutions for maintaining a personal blog, such as building it with Next.js are setting up WordPress.

The pros:

• using the Obsidian flavor of markdown with wikilinks - I already maintain a private wiki using Obsidian, so it’s nice to think that I can just add some polish to my notes and they are ready for publishing.
• batteries included: Quartz generates an RSS feed, a sitemap, and the cool-but-useless graph on the right
• cheap: static sites are easy to host for free. This one lives on Vercel

The cons:

• breaking old URLs: if I move a note, its URL will change and old links I’ve shared will stop working. A full-fledged CMS like Wordpress would solve this by tracking old names and redirecting. With Quartz, I need to be careful to leave notes in their original places.
• no server-side code: Quartz is a static site generator, as opposed to frameworks like Next.js which allow mixing static and dynamic content. This limits my possibilities in adding interactive elements to the notes.

The wishlist / todo:

• track old names of notes and generate redirect pages. I’ve realized there is already support for redirects from the aliases defined in the frontmatter, so I just need:

  1. a script to record path history automatically
  2. extend the redirects functionality to handle full paths, in case the note was moved between folders

• Do not create <a> tags for links to missing pages

  Quartz does not check which wikilinks lead to an existing page. In my private wiki, I often create links to pages which not exist yet. Including them in the published note leads to the bad user experience of hitting a 404 page. When processing the source files, it should be possible to check whether the target exists and mark the dead link differently (or render it as plain text).

  DONE I added a hacky check to link resolution. Unfortunately does not respect the filtered out files (not marked for publication), for those links are still generated.

• there is a WIP PR in quartz (https://github.com/jackyzha0/quartz/pull/866) to have per-directory RSS feeds. This supports my idea to have a directory in quartz double as a more professional “blog” with better articles.

Setup steps

Steps I’ve done so far in setting up this website

1. Fork https://github.com/jackyzha0/quartz and clone locally
2. Adjust quartz.config.ts: change baseUrl, page title, add Plugin.ExplicitPublish() to filters, add git to Plugin.CreatedModifiedDate config.
3. Set up a Vercel project linked to the github repository
4. Configure Vercel Analytics - this required modifications in quartz/plugins/emitters/componentResources.ts to add the script tag
5. Switch Quartz imagery and links to my own
   1. Change footer links configuration in quartz.layout.ts
   2. Remove <meta og:image> from quartz/components/Head.tsx . This image is used for example as the preview when sharing links in instant messengers. Until I have a better replacement, I don’t want to use the default quartz banner.
   3. Update quartz/static/logo.png with my custom favicon
6. Add scripts to package.json to simplify pulling new content from my wiki, which is stored in a different directory
7. Modify quartz/plugins/emitters/404.tsx to show the left sidebar with Search and Explorer even on the “404 Not Found” page