AkrOps

Quartz

3 min read

Quartz is a static-site generator by Jacky Zhao that transforms Markdown content into fully functional websites. This Digital garden was created with this tool.

This is a collection of notes and resources on Quartz.

Directory structure

In Obsidian, it’s common to throw a gazillion notes into a directory. People will often put all notes in the root dir of the vault. I believe that Quartz content, on the other hand, should have at least a minimal directory structure for the following reasons:

  • Quartz generates breadcrumbs based on it, making navigation a bliss.
  • If there are tens or even hundreds of pages in a single directory, users might be overwhelmed when using the left navigation panel.
  • If you need to navigate your content via CLI or a file explorer, or use a code editor, both local (vim, VSCode) and online (GitHub, GitLab), you will probably be overwhelmed as well (at least eventually).
  • You can still leverage all of the Obsidian features to link your thoughts and ideas (and that’s the whole point), regardless of the subjacent directory structure, and of course you can (and probably should) use Obsidian itself to edit your content.
  • Your digital garden content can live in its own directory inside your Obsidian vault, so you can create notes that you’d like to publish inside the Quartz dedicated directory, or move existing ones into it.
  • Obsidian Sync does not sync dotfiles, including .git and .gitignore, so you can keep your digital garden under version control in its own repository if you wish.

If you are afraid you might accidentally publish notes to a public digital garden (especially what you hold in your personal vault), you can leverage a very useful filter Quartz offer: Plugin.ExplicitPublish()

// quartz.config.ts
plugins: {
	transformers: [...],
	filters: [Plugin.ExplicitPublish()],
	emitters: [...],
}

This will prevent a note from being publish unless it has the frontmatter property publish: true

Another useful filter is Plugin.RemoveDrafts(), which filters out all pages with draft: true in their frontmatter.

Topics to cover

  • Draft and publish boolean frontmatter values
    • Related config options
  • Vault within a Vault - Can this cause any problems when used in combination with Obsidian sync?
    • Keep content in a separate directory under an Obsidian Vault
  • Casing (capitalization) for directories is respected.
    • You can alter the section title in the index.md file frontmatter
    • Peculiarities of links to directories
  • Sync repo to both the Quartz upstream as well as my own origin remote
  • Build and publish/deploy public

Resources

Graph View