detailed notes on how i set-up and configure this digital garden.
install and configure
- 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 calledgarden. (you may call itquartz, orwebsite, orblog, or something else. but in this document, whenever i refer to a folder calledgarden, i am referring to the main folder into which quartz was cloned.) - (optional) instead of using the default
v5branch, create amainbranch 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 defaultv5branch, and ignore any instructions (in this document) where i ask you to replacev5bymain. - initialise quartz using the
obsidiantemplate.
- if using a free github account, our github-repo needs to be
- customise quartz by editing configurations in
quartz.config.yaml.- update
pageTitle - optional updates:
analytics: nulllocale: en-GB- plugins:
footer: disable (or customise)- i want to disable the
graphalso, but it seems to make the backlinks feature malfunction somewhat, so i leave it enabled.
- update
- get quartz, and follow the installation steps. keep this in mind:
- obsidian:
- download obsidian and open it.
- create a new vault, like so:
- go to
file>open vault... in the modal that opens, selectcreate new vault. on the next step,- for
vault name: typecontent. - and for
location: pressbrowseand select the main folder into which quartz was installed, i.e.,garden. (be careful not to select thegarden/contentfolder here.)
- for
- this will create a
.obsidianfolder inside the existinggarden/contentfolder; and the vault will open in obsidian.
- go to
- 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 thetemplatessection)- also make this update in quartz’s config file. open
quartz.config.yaml, and underconfiguration: ignorePatterns:, renametemplatesto_templates.
- also make this update in quartz’s config file. open
- attachments:
_attachments(in thefiles & linkssection) - regular notes:
notes(in thefiles & linkssection) - new file location for daily-notes:
log(in thedaily notessection)
- page templates:
- whenever we customise a file-location, we need to create the corresponding folders:
_templates,_attachments,logandnotes. (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 fromYYYY-MM-DDtoYYYYMMDD
- set date format to
- in
file recovery- increase
history length(eg. 1000)
- increase
- set locations for different files:
- in
core plugins,- enable
slash commands - enable
daily notes
- enable
- (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.trashfolder (to make them easier to recover in-case of accidental deletion).- also: add
.trashto.gitignore
- also: add
- (these customisations are a me thing, and very-much optional. please stick to obsidian’s vanilla setup.)
write.
at this point, this is good to know:
- most files in the
contentfolder will be.mdfiles. - 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 asindex, but add frontmatter liketitle: "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: trueorpublish: falsemay—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 possiblevery inconvenient to rename a tag (say, change#ideasto#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.
- unlike logseq, obsidian doesn’t offer pages for tags. also: it is
- 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
.basefile to view which attachments don’t have any backlinks, and use it to prune such files. so, i make aprune-orphans.basefile in a_helper_filesfolder. i also ask quartz to not emit this folder to the website by adding it toquartz.config.yml(underconfigurations: 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
gardendirectory. - in the terminal, type:
npx quartz build --serve. - the site will be live on http://localhost:8080
- open the terminal at the
- (optional) to speed up build/serve times, the custom og images plugin can be disabled in the
quartz.config.tsfile (underplugins>emitters).
emit to github pages
(i repeat: regularly commit and push changes to github.)
- on github: in the repo’s
settings, underpages, 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 localquartzfolder,- open your terminal in the
quartzfolder. - Run:
npm install @quartz-themes/default - This will update your
package.jsonandpackage-lock.jsonfiles.
- open your terminal in the
- when github pages tries to build the website, it may run into an error (
- keep committing changes to the
mainbranch. - 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
v5branch tomain.
- since we want the website to auto-update on any update (whether to quartz or content), change the default
- create
- ‘missing dependency’ fix
- on github: in the repo’s
settings,- (optional) change the default branch from
v5tomain. - under
pages, ensure that:- github pages are enabled.
- source is
github actions. // there’s no need to select any workflow.
- under
environments, go into thegithub-pagesenvironment, and change the allowed branch fromv5tomain.
- (optional) change the default branch from
- locally: commit all changes to
main; push. on github: check github actions. if it completes successfully, the website will be emitted to github-pages.