Whoever uses this template deals with four programs. You do not have to be able to operate all four — QuartzControl takes two of them off your hands — but you should know what each one does.
Obsidian — where the writing happens
Obsidian is a program for notes. It stores every note as an ordinary text file with the extension
.md, written in Markdown: a simple notation in which **bold** becomes bold and # Heading
a heading. A folder full of such files is called a vault in Obsidian. All the notes of this
site live in one vault; chapter 2 shows what you can write in it.
Quartz — what turns it into a website
Quartz is a static site generator: a program that turns a folder full of Markdown files into a folder full of HTML pages — HTML being the language a browser understands. This process is called a build. The result is a finished website without a database and without a program behind it, which can be put on any web space. Quartz knows Obsidian’s notation: wikilinks, callouts and embedded images are translated correctly.
Quartz consists of plugins — building blocks with one job each: 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
plugins there are and how they are set stands in a configuration file called
quartz.config.yaml in the project.
QuartzControl — where the operating happens
QuartzControl is the interface for Quartz. Without it you operate Quartz from the command line and edit the configuration in a text editor; with it you click. QuartzControl creates projects, links the content to a vault, installs plugins, changes colours and typefaces, builds page grids in an editor, starts the preview, builds the site and publishes it. A project is a folder with a Quartz installation; QuartzControl can manage several of them.
This template is built with QuartzControl and made for QuartzControl: everything it sets is visible and changeable in QuartzControl.
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; you can restore any earlier state and compare two states. Such a comparison is called a diff and shows line by line what changed. A folder whose history git keeps is called a repository.
You do not have to be able to operate git to use this template. It still appears in three places: QuartzControl needs it for new projects, for plugins from a git source and for its snapshots — and takes the machine’s git or brings one of its own. The date of a page can be read from git by Quartz (not here; why, stands under 4.1 – Title, description, date). And whoever publishes their site through a git repository, on GitHub Pages for instance, sends it there with git.
How they fit together
Obsidian ─writes─▶ Vault ◀─symlink─ Project ─Quartz builds─▶ Website ─▶ Web space
▲ ▲
└────── QuartzControl ────┘
The vault is the source. The project points to it with a symlink — a link in the file system that makes a folder appear in a second place without copying it. Quartz reads the content through this link, builds the site from it, and QuartzControl controls both. How that goes in detail: 1.3 – From note to website.