my_quartz_deployment

4 min read

Link:

Intro

This site is built locally on my laptop and deployed to an OpenBSD server. My Quartz deployment is based on a configuration by Aster Hu. https://www.asterhu.com/post/20240220-publish-org-roam-with-quartz-oxhugo/

Config

Folder Hierarchy

My org folder is called org/, which contains my index, main, and todo files. I have a second folder which is org/roam/ which lets org store unstructured nodes as it pleases.

Config.org publish section

Here is the relevant section from my Emacs Config.

Org-Publish

My goal here is to use Org- publish in order to publish an org-roam Zettelkasten. https://www.asterhu.com/post/20240220-publish-org-roam-with-quartz-oxhugo/ I like this workflow which uses ox-hugo and Quartz. Quartz is an interesting too that I had not heard of before.

  • Require ox-hugo

    ox-hugo is a plugin which formats org files for Hugo. Quartz has an ox-hugo plugin by default, which lets me import these files to deploy them.

    (use-package ox-hugo
  :ensure t   ;Auto-install the package from Melpa
  :pin melpa  ;`package-archives' should already have ("melpa" . "https://melpa.org/packages/")
  :after ox
  )
 
(setq org-hugo-base-dir "/home/roerick/dev/quartz")

  • Modify Capture Templates for org-roam

    Modifying the capture templates produces healthy defaults for publishing using the hugo syntax. the 'noexport' tag can be removed in order to enable publishing.

    (setq org-roam-capture-templates
      '(("o" "moc" plain
         "\n*Link*:  %?\n\n"
         :if-new (file+head "${slug}.org" "#+title: ${title}\n#+filetags: :moc:\n#+hugo_section: roam\n#+date: %u\n#+hugo_lastmod: %u\n#+hugo_tags: noexport\n")
         :immediate-finish t
         :unnarrowed t
         :empty-lines-after 1)))

  • Modify timestamp on org file after safe

    This is a save hook which runs on org files. It uses regex to modify the date upon saving. I'm not sure if this is the cleanest or best way to to this, as I believe this code runs every time I save any file.

     
(defun my-org-time-stamp-setup ()
  (setq time-stamp-active t
        time-stamp-start "#\\+hugo_lastmod:[ \t]*"
        time-stamp-end "$"
        time-stamp-format "$$%Y-%m-%d$$")
  (when (eq major-mode 'org-mode)
    (time-stamp)))
 
(add-hook 'before-save-hook 'my-org-time-stamp-setup)

org/.dir-locals.el

This file lives in the root of my org/ directory. I guess this enables settings folder wide. I'm not exactly sure how emacs knows how to read this. This tells emacs that any time a file is in my org/roam/ directory, it should be automatically exported to Quartz.

#+INCLUDE: "~/org/.dir-locals.el"

Current Issues / Possible improvements

TODO index.org/index.html must be manually exported

Because index.org lives outside of my org/roam/ directory, I currently have to manually export index.html if I make changes. In addition, if I were to add other custom pages kept in my main org directory, I would have to update these manually as well. I think I can add update triggers on a per-file basis.

TODO Everything in Quartz lives in a roam/ directory

So, this one is kind of a weird thing in ox-hugo. Files are exported using the .dir-locals.el configuration. During export, files are also placed in the roam folder based on the frontmatter which is loaded in through a blog post. Links in the knowledge base must match links in Quartz in order for them to not 404.

TODO ox-hugo is kind of problematic

I think ox-hugo is a pretty neat tool, but overall it perhaps isn't completely suited to my workflow. I definitely prefer being able to publish an entire project. However, the limitations of org publish and the big benefits offered by Quartz ultimately make this workflow preferable.

TODO I don't know how link parsing works at all

This is probably the root of the last two problems, it's a skill issue. I guess this is in ox-hugo's domain. I need to add some custom link export capabilities for some custom link protocols which I've written. I think I can still do this in org-export, but I have no idea. Here is the relevant source code, which implements the export function for my custom // link protocol. I just don't know enough about the ox-hugo function to understand if it uses the standard org-export interface to do its thing.

 
(defun org-bible-export (path desc format)
  "Export a Bible link."
  (cond
   ((eq format 'html) (format "<a href=\"https://www.biblegateway.com/passage/?search=%s\">%s</a>" path (or desc path)))
   ((eq format 'latex) (format "\\href{https://www.biblegateway.com/passage/?search=%s}{%s}" path (or desc path)))
   ((eq format 'ascii) (format "%s" (or desc path)))
   (t path)))
 
 
(org-link-set-parameters "bible"
                         :follow #'org-bible-follow
                         :export #'org-bible-export)

TODO My deployment is a mess

I'm manually deploying with scp and since I don't have file permissions on /var/www, I have to log in and copy the files in once I've SCP'd. It's an embarrassing situation which I can surely fix with git.

TODO I'd like to add RSS

I don't really know if or how Quartz handles RSS

TODO I have the wierd compulsion to rewrite this entire stack in OCAML

I may be beyond helping at this point, somebody please get me a notebook.

Backlinks