Quartz

Overview

Quartz is a Static Site Generator similiar to Hugo. I use this ssg for creating my Digital Garden from my Emacs Org-Mode files.

For this workflow you need the ox-hugu package for Emacs.

Content

Initialize site with Quartz

• Clone the repository

git clone https://github.com/jackyzha0/quartz.git

• Go to repository and install npm

cd quartz
npm i

• Create Quartz

npx quartz create

• Follow the instructions.

• Your Quartz is ready to run locally with

npx quartz build --serve

Setup Quartz for Emacs

• add Plugin.OxHugoFlavoredMarkdown to your quartz.config.ts file
  • this is to make sure, that Quartz understands the markdown file style created by ox-hugo

plugins: {
  transformers: [
    // ...
    Plugin.OxHugoFlavouredMarkdown(),
    Plugin.GitHubFlavoredMarkdown(),
    // ...
  ],
},

Setup Emacs for Quartz

• create a .dir.locals.el file with some settings in you roam dir (more info)
  • this is for auto exporting your org-roam files when saving them

((org-mode . ((eval . (org-hugo-auto-export-mode))
                  (org-hugo-base-dir . "/path/to/quartz/content/")
                  (org-hugo-front-matter-format . "yaml"))))

• you can prevent files from auto export via the #+HUGO_TAGS: noexport in your org-file

Setup your local Quartz with you GitHub Repository

Most people use a GitHub Pages site for publishing their Quartz project. For this you just need to create a repo and under Settings→Pages you need to setup the build and deployment source to GiHub Actions.

After this create a deploy.yml file in your quartz/.github/workflows/ dir.

Make sure that your remote and upstream is setup in your git project:

# list all the repositories that are tracked
git remote -v
 
# if the origin doesn't match your own repository, set your repository as the origin
git remote set-url origin REMOTE-URL
 
# if you don't have upstream as a remote, add it so updates work
git remote add upstream https://github.com/jackyzha0/quartz.git

Now you can sync you Qartz project with your GitHub Page via:

npx quartz sync

Setup your Quartz on your private Server

I run my Quartz on my private Apache Server. Since Quartz is creating nicely designed .html with .css and some .js when you build your project, you just have to upload your public folder to your server to run it where you want it.

404 Error

Quartz can produce a pretty looking 404 error. For this you need some tewaking on your server. I run my Quartz in a Subdirectory of my Website. In this you have to create this .htaccess file and replace MY_SUB_DIR with the correct Sub Dir Name. This is linking every 404 Error to the 404.html in your Sub Dir.

Handling Images

On my system Quartz has problems with linking images correctly. I needed to put a Symlink into my content dir. This solved it

# cd to your content dir and create this symlink
ln -s static/ox-hugo ox-hugo

Terminal Commands

• set up a local server to preview your content

npx quartz build --serve

• sync your Quartz project with the Repo
• this will deploy your project to your website

npx quartz sync

• To fetch the latest Quartz updates, simply run

npx quartz update

Footer

Links

• i discovered Quartz via Aster Hu’s Blog
  • you can find here the basic setup for Quartz and releasing your Org-Roam files via Ox-Hugo in Emacs
• This is the official Quartz Website
• some more information for configuring Quartz for Org-Roam file export via ox-hugo: Link