Working with QuartzControl means dealing with four programs. You need not be able to operate all four — QuartzControl takes two off your hands — but you should know what each does.
Obsidian — where the writing happens
Obsidian is a program for notes. It stores every note as an ordinary text file ending in .md,
written in Markdown. A folder full of such files is called a
vault in Obsidian.
Obsidian is not a requirement. Any folder with Markdown files will do, whatever wrote them. But the path is built with Obsidian in mind: QuartzControl can point the content folder straight at a vault, and Quartz understands Obsidian’s wikilinks, callouts and embedded images.
Quartz — where the website comes from
Quartz is a static site generator: a program that turns a folder full of Markdown files into a folder full of HTML pages. That process is called a build. The result is a finished website with no database and no program behind it, which can be put on any webspace.
Quartz consists of plugins — each with one job: one builds the
explorer on the left, one the table of contents on the right, one the search, one reads a file’s
date. Which are active and how they are configured is in quartz.config.yaml in the project. That
file is exactly what QuartzControl edits in several places.
QuartzControl — where the operating happens
What QuartzControl does is on the previous page. For this chapter one thing matters most: a project is a folder holding a Quartz installation, and QuartzControl can manage several. The start screen is the list of those projects; everything else applies to one of them.
git — where the history is kept
git is a program that records the history of files. Every saved state is called a commit and carries a date, an author and a description; any earlier state can be restored. A folder whose history git keeps is called a repository.
You need not be able to operate git. It turns up in four places, in three of them invisibly:
- A new project comes about by fetching Quartz from GitHub — that is git.
- A plugin from a git source is fetched and built — that too.
- Every snapshot is a commit, but in a history of its own that only QuartzControl knows about and that never touches yours.
- git only becomes visible under Git sync and when publishing to a branch — there it really is about push and pull.
QuartzControl uses the machine’s git as soon as one answers — your own .gitconfig and your own
credential helpers then keep applying. If there is none, QuartzControl brings its own.
How they fit together
Obsidian ─writes─▶ Vault ◀─link─ Project ─Quartz builds─▶ Website ─▶ Webspace
▲ ▲
└───── QuartzControl ────┘
The vault is the source. The project points at it with a link, Quartz reads the content through it and builds the website, and QuartzControl steers both ends: what Quartz does, and where the result goes.
The vault need not be outside. Anyone without one lets QuartzControl create an empty content folder inside the project and writes in there — the arrow to the left in the drawing above is then simply missing.