A change to this site begins in Obsidian and ends on a web space. In between lie four steps, and each has a place.
1 · Writing — in Obsidian
You open the vault in Obsidian and write. A new file is a new page; a folder a branch in the
navigation; a [[wikilink]] a reference that the graph and the backlinks see. Header lines between
two --- at the very top of the file — the frontmatter — give the page its title,
description, date and tags; everything you can control with it stands in
4 – Controlling a page.
None of this needs the website yet. You can write for days without building.
2 · Looking — the preview in QuartzControl
Under Preview & Build QuartzControl starts a dev server: Quartz builds the site once and then again
after every saved change, and a browser window shows it at an address like localhost:8080. That
is your own machine; nobody else sees this page. Whoever saves in Obsidian sees the page in the
browser seconds later.
3 · Building — the build
The same area can also build the site without showing it: Quartz reads all notes, applies the
plugins — resolving links, generating the table of contents, indexing the search, creating pages
for folders and tags — and writes finished HTML files into the output folder public/. A draft
(draft: true in the frontmatter) is left out; see
4.2 – Draft and unlisted.
4 · Publishing
Under Publish QuartzControl sends the output folder to a target: a folder, a server via rsync, a git repository for GitHub Pages for instance, or it triggers a webhook. The credentials for that the app keeps encrypted. From that moment on the page is public.
Where the content lives — and why as a symlink
A Quartz project expects its notes in the folder content/. Here this folder is not a folder but a
symlink: a link that points to the Obsidian vault. Quartz sees the vault through the link as if
it lay in the project. The advantage: there is only one copy of the notes. You write in Obsidian,
and the project has it at once.
QuartzControl creates this link — under Configuration → Content folder, when you link the content to an existing folder instead of copying it. Both can be changed later.
What a symlink costs
Two things do not follow the link. Snapshots — the backups QuartzControl takes before every larger intervention — leave the content out as soon as
content/is a link; the vault has to be backed up itself, here through its own git. And the plugin that reads a page’s date from git miscalculates at the link and falls back to the file system — see 4.1 – Title, description, date.
Getting the template into a project of your own
Whoever wants not this site but one of their own with this design goes the other way round: create a new project in QuartzControl, link your own vault, then import the template under Templates. QuartzControl shows beforehand which parts the package contains and what in the project is replaced by them, and takes a snapshot. What comes along and what does not: 6.8 – The template package.