org-mode + org-roam + quartz + gitlab/github

Table of Contents

org-mode + org-roam + quartz + gitlab/github

  1. https://quartz.jzhao.xyz/#-get-started
  2. https://www.asterhu.com/post/20240220-publish-org-roam-with-quartz-oxhugo/

Pros of this method

  1. The built-in features in the UI are great.
    1. Exact match search,
    2. preview for the pages with the content, etc.
  2. We don’t have to use custom hugo themes
  3. Once we update the content folder and push it to gitlab/github, the pipeline should pick up the files from there and update the live website.
  4. This lets us update the notes from any computer - as long as it can update the content folder with the necessary changes.
  5. There is no need to build pagefind index because the search feature is built into quartz. The pagefind index can be huge and this is a huge advantage when it comes to the amount of data that has to be checked into gitlab/github.

Cons of this method

  1. If we build the website using this approach, if we open the website from a browser in a phone, the browser is crashing and the entire phone seems to be getting disconnected from the internet.
    1. Have to restart the phone to get it working again.
  2. The links in the table of contents in the UI don’t seem to be working.
  3. There is always a possibility that we may run into errors like this in the CI/CD pipelines. And that may be out of our control - considering that it uses package.json for dependency management. 
    [23:17:56.072] Cloning gitlab.com/explorer436/programming-notes (Branch: main, Commit: f64ba15)
[23:17:58.135] Cloning completed: 2.063s
[23:17:58.465] Restored build cache from previous deployment (ARHzq38JNkNZXuEWHF6JcQ3WezRN)
[23:17:58.570] Running build in Washington, D.C., USA (East) – iad1
[23:17:58.965] Running "vercel build"
[23:17:59.364] Vercel CLI 41.3.2
[23:18:00.118] Warning: Detected "engines": { "node": ">=20" } in your `package.json` that will automatically upgrade when a new major Node.js Version is released. Learn More: http://vercel.link/node-version
[23:18:00.126] Installing dependencies...
[23:18:02.990]
[23:18:02.991] up to date in 2s
[23:18:02.991]
[23:18:02.991] 180 packages are looking for funding
[23:18:02.992]   run `npm fund` for details
[23:18:04.063]
[23:18:04.064]  Quartz v4.4.0
[23:18:04.064]
[23:18:05.841] Error: Cannot find package '/vercel/path0/node_modules/zwitch/index.js' imported from /vercel/path0/node_modules/hast-util-to-html/lib/handle/index.js
[23:18:05.841]     at legacyMainResolve (node:internal/modules/esm/resolve:204:26)
[23:18:05.842]     at packageResolve (node:internal/modules/esm/resolve:778:12)
[23:18:05.842]     at moduleResolve (node:internal/modules/esm/resolve:854:18)
[23:18:05.842]     at defaultResolve (node:internal/modules/esm/resolve:984:11)
[23:18:05.842]     at ModuleLoader.defaultResolve (node:internal/modules/esm/loader:685:12)
[23:18:05.842]     at #cachedDefaultResolve (node:internal/modules/esm/loader:634:25)
[23:18:05.842]     at ModuleLoader.resolve (node:internal/modules/esm/loader:617:38)
[23:18:05.846]     at ModuleLoader.getModuleJobForImport (node:internal/modules/esm/loader:273:38)
[23:18:05.847]     at ModuleJob._link (node:internal/modules/esm/module_job:135:49) {
[23:18:05.847]   code: 'ERR_MODULE_NOT_FOUND'
[23:18:05.847] }
[23:18:05.873] Error: Command "npx quartz build" exited with 1
[23:18:06.301]

Set-up

  1. Init new quartz folder using quartz command: https://quartz.jzhao.xyz/
  2. In GitRepositories, create a folder using the name you want for your repository.
  3. Copy contents from quartz folder into the repository folder.
  4. In the repository folder, git init and point it to your destination repository in gitlab/github.
    1. git remote add origin git@gitlab.com:explorer436/programming-notes.git
  5. Replace the README.md file with your own.
  6. Copy/create org folder with your own org files that use org-roam.
  7. Copy/create files needed to convert org files into markdown files - preferably, into a separate folder.
  8. Convert all the org files into markdown files.
    1. Create a static directory manuallally. If not, we may run into this error: 
      Error: user-error ("Please create the /home/explorer436/Downloads/GitRepositories/programming-notes/static/ directory")
  9. Test the set-up in local using a browser.
    1. Build and Serve your quartz website.
    2. npx quartz build --serve
    3. Things we may have to do to make sure that quartz plays nice with the generated markdown files.
      1. The front matter of the markdown files has to be in yaml format (as opposed to toml or json format)
      2. Image handling between org-mode and Quartz
        1. For image linking, it becomes a bit tricky.
        2. Ox-hugo will copy images to static/ folder, which Quartz doesn’t use and will be emitted.
        3. I didn’t find the option to change the image output directory in ox-hugo.
        4. Just create a script to copy all the images from static/ox-hugo to content/ox-hugo.
      3. Enable compatibility in quartz with the hugo-flavoured markdown exported from org-mode
        1. Simply add Plugin.OxHugoFlavouredMarkdown to the quartz.config.ts file 
           plugins: {
   transformers: [
     // ...
     Plugin.OxHugoFlavouredMarkdown(),
     Plugin.GitHubFlavoredMarkdown(),
     // ...
   ],
},
    4. Change pageTitle
      1. In quartz.config.ts file 
        pageTitle: "🪴 explorer436"
  10. Push changes to gitlab/github.
  11. Set up the website using Vercel. See Hosting platforms
  12. Add .gitinit file and add node_modules to it.

Customizing the layout of quartz template

If you want to customize the page set-up, like move things around and expand the width of the page, see this repo for reference: https://github.com/ellie/notes?tab=readme-ov-file

Links to this note