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 --serveSetup Quartz for Emacs
- add
Plugin.OxHugoFlavoredMarkdownto yourquartz.config.tsfile- this is to make sure, that Quartz understands the markdown file
style created by
ox-hugo
- this is to make sure, that Quartz understands the markdown file
style created by
plugins: {
transformers: [
// ...
Plugin.OxHugoFlavouredMarkdown(),
Plugin.GitHubFlavoredMarkdown(),
// ...
],
},Setup Emacs for Quartz
- create a
.dir.locals.elfile 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: noexportin 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.gitNow you can sync you Qartz project with your GitHub Page via:
npx quartz syncSetup 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-hugoTerminal 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