detailed notes on how i set-up and configure this digital garden.

install and configure

  1. quartz:
    • get quartz, and follow the installation steps. keep this in mind:
      • if using a free github account, our github-repo needs to be public, else github won’t allow us to emit the website to ‘github pages’.
        • if you’re new to git, learngitbranching is a good place to start before diving into this project.
      • i like to call this project garden. so, on my computer, the folder in which quartz sits is usually called garden. (you may call it quartz, or website, or blog, or something else. but in this document, whenever i refer to a folder called garden, i am referring to the main folder into which quartz was cloned.)
      • (optional) instead of using the default v5 branch, create a main branch to track all changes (customisations to quartz and obsidian, and content updates) to the repo. this is a me thing ; i like to segregate things ; it creates extra work, but usually helps me recover from mistakes or tidy-up messes better. if you’re new to coding, git, and what-not, skip this; just commit to quartz’s default v5 branch, and ignore any instructions (in this document) where i ask you to replace v5 by main.
      • initialise quartz using the obsidian template.
    • customise quartz by editing configurations in quartz.config.yaml.
      • update pageTitle
      • optional updates:
        • analytics: null
        • locale: en-GB
        • plugins:
          • footer: disable (or customise)
          • i want to disable the graph also, but it seems to make the backlinks feature malfunction somewhat, so i leave it enabled.
  2. obsidian:
    • download obsidian and open it.
    • create a new vault, like so:
      • go to file > open vault... in the modal that opens, select create new vault. on the next step,
        • for vault name: type content.
        • and for location: press browse and select the main folder into which quartz was installed, i.e., garden. (be careful not to select the garden/content folder here.)
      • this will create a .obsidian folder inside the existing garden/content folder; and the vault will open in obsidian.
    • customise obsidian vault’s preferences:
      • (these customisations are a me thing, and very-much optional. please stick to obsidian’s vanilla setup.)
        • set locations for different files:
          • page templates: _templates (in the templates section)
            • also make this update in quartz’s config file. open quartz.config.yaml, and under configuration: ignorePatterns:, rename templates to _templates.
          • attachments: _attachments (in the files & links section)
          • regular notes: notes (in the files & links section)
          • new file location for daily-notes: log (in the daily notes section)
        • whenever we customise a file-location, we need to create the corresponding folders: _templates, _attachments, log and notes. (if correctly-named folder don’t exist, new notes just go into the root folder, i.e., garden/content.)
        • in daily notes,
          • set date format to custom, and change the syntax from YYYY-MM-DD to YYYYMMDD
        • in file recovery
          • increase history length (eg. 1000)
      • in core plugins,
        • enable slash commands
        • enable daily notes
      • (optional) enable community plugins, and, and install plugins:
        - image converter
        - update modified date
        - tag page
      • under files & links, set deleted files to move to obsidian’s .trash folder (to make them easier to recover in-case of accidental deletion).
        • also: add .trash to .gitignore

write.

at this point, this is good to know:

  • most files in the content folder will be .md files.
  • while obsidian is a convenient tool for writing and managing your content, these files can be opened/edited using any text-editor.
  • however, if we plan to use quartz to emit the files to a website — which, we do, because it’s easy for students to pick this up and start writing-in-public quickly — , then obsidian is convenient because (among other reasons) quartz is optimised for the flavour of markdown that obsidian uses.

instructions for writing:

  • the vault is open in obsidian. so, write!
    • read about basic markdown syntax you can use while creating notes.
    • i suggest updating index.md. (when we emit the website, quartz will turn this into your website’s home page.) keep the file-name as index, but add frontmatter like title: "hello." to the file.
  • from time to time, commit and push changes to git. make it a habit.

tips:

  • you can copy over existing files (from an existing obsidian vault, or just any folder in which you had notes in a suitable format). paste those items into appropriate sub-folders (eg. log, notes, etc).
  • do not add any private items. while notes marked as draft: true or publish: false may—depending on the plugins you use—not get emitted to the final website, all your content (and every version of it) will still sit among the commits in a public git repository.
  • about tags:
    • unlike logseq, obsidian doesn’t offer pages for tags. also: it is not possible very inconvenient to rename a tag (say, change #ideas to #thoughts). so, i don’t like using tags (or have to be very disciplined if i must use them).
    • also, the way quartz currently emits tags on a page is just ugly. so.
  • when we add images but later delete them (or choose not to use them in any post), those images stay in the attachments directory and take up unnecessary space. we can create a .base file to view which attachments don’t have any backlinks, and use it to prune such files. so, i make a prune-orphans.base file in a _helper_files folder. i also ask quartz to not emit this folder to the website by adding it to quartz.config.yml (under configurations: ignorePatterns).

sidenote: i keep this garden-setup.md file in the root folder, next to index.md.

emit locally

  • serve (preview) the website:
    • open the terminal at the garden directory.
    • in the terminal, type: npx quartz build --serve.
    • the site will be live on  http://localhost:8080
  • (optional) to speed up build/serve times, the custom og images plugin can be disabled in the quartz.config.ts file (under plugins > emitters).

emit to github pages

(i repeat: regularly commit and push changes to github.)

  • on github: in the repo’s settings, under pages, ensure that:
    • github pages are enabled.
    • source is github actions. // there’s no need to select any workflow.
  • locally:
    • ‘missing dependency’ fix
      • when github pages tries to build the website, it may run into an error (Cannot find module '@quartz-themes/default'). to preemptively fix this, go to the local quartz folder,
        • open your terminal in the quartz folder.
        • Run: npm install @quartz-themes/default
        • This will update your package.json and package-lock.json files.
    • keep committing changes to the main branch.
    • setup github-actions
      • create deploy.yml. instructions.
      • update deploy.yml:
        • since we want the website to auto-update on any update (whether to quartz or content), change the default v5 branch to main.
  • on github: in the repo’s settings,
    • (optional) change the default branch from v5 to main.
    • under pages, ensure that:
      • github pages are enabled.
      • source is github actions. // there’s no need to select any workflow.
    • under environments, go into the github-pages environment, and change the allowed branch from v5 to main.
  • locally: commit all changes to main; push. on github: check github actions. if it completes successfully, the website will be emitted to github-pages.