Welcome to Quartz 4

Jun 13, 20242 min read

Quartz is a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites. Thousands of students, developers, and teachers are already using Quartz to publish personal notes, websites, and digital gardens to the web.

🪴 Get Started

Quartz requires at least Node v18.14 and npm v9.3.1 to function correctly. Ensure you have this installed on your machine before continuing.

Then, in your terminal of choice, enter the following commands line by line:

git clone https://github.com/jackyzha0/quartz.git

cd quartz

npm i

npx quartz create

This will guide you through initializing your Quartz with content. Once you’ve done so, see how to:

Writing content in Quartz

Configure Quartz’s behaviour

Change Quartz’s layout

Home

❯

Layout

Layout

Jun 13, 20242 min read

Certain emitters may also output HTML files. To enable easy customization, these emitters allow you to fully rearrange the layout of the page. The default page layouts can be found in quartz.layout.ts .

Each page is composed of multiple different sections which contain QuartzComponents . The following code snippet lists all of the valid sections that you can add components to:

quartz/cfg.ts

export interface FullPageLayout {

head: QuartzComponent // single component

header: QuartzComponent[] // laid out horizontally

beforeBody: QuartzComponent[] // laid out vertically

pageBody: QuartzComponent // single component

left: QuartzComponent[] // vertical on desktop, horizontal on mobile

right: QuartzComponent[] // vertical on desktop, horizontal on mobile

footer: QuartzComponent // single component

}

These correspond to following parts of the page:
Note

There are two additional layout fields that are not shown in the above diagram.
1. head is a single component that renders the <head> tag in the HTML. This doesn’t appear visually on the page and is only is responsible for metadata about the document like the tab title, scripts, and styles.
2. header is a set of components that are laid out horizontally and appears before the beforeBody section. This enables you to replicate the old Quartz 3 header bar where the title, search bar, and dark mode toggle. By default, Quartz 4 doesn’t place any components in the header .
Quartz components , like plugins, can take in additional properties as configuration options. If you’re familiar with React terminology, you can think of them as Higher-order Components.

See a list of all the components for all available components along with their configuration options. You can also checkout the guide on creating components if you’re interested in further customizing the behaviour of Quartz.

Style

Most meaningful style changes like colour scheme and font can be done simply through the general configuration options. However, if you’d like to make more involved style changes, you can do this by writing your own styles. Quartz 4, like Quartz 3, uses Sass for styling.

You can see the base style sheet in quartz/styles/base.scss and write your own in quartz/styles/custom.scss .

Note

Some components may provide their own styling as well! For example, quartz/components/Darkmode.tsx imports styles from quartz/components/styles/darkmode.scss . If you’d like to customize styling for a specific component, double check the component definition to see how its styles are defined.

Build and preview Quartz

Sync your changes with GitHub

Home

❯

Setting up your GitHub repository

Setting up your GitHub repository

Jun 13, 20242 min read

First, make sure you have Quartz cloned and setup locally.

Then, create a new repository on GitHub.com. Do not initialize the new repository with README , license, or gitignore files.

At the top of your repository on GitHub.com’s Quick Setup page, click the clipboard to copy the remote repository URL.

In your terminal of choice, navigate to the root of your Quartz folder. Then, run the following commands, replacing REMOTE-URL with the URL you just copied from the previous step.

# list all the repositories that are tracked

git remote -v

# if the origin doesn't match your own repository, set your repository as the origin

git remote set-url origin REMOTE-URL

# if you don't have upstream as a remote, add it so updates work

git remote add upstream https://github.com/jackyzha0/quartz.git

Then, you can sync the content to upload it to your repository. This is a helper command that will do the initial push of your content to your repository.

npx quartz sync --no-pull

fatal: --[no-]autostash option is only valid with --rebase

You may have an outdated version of git . Updating git should fix this issue.

In future updates, you can simply run npx quartz sync every time you want to push updates to your repository.
Flags and options

For full help options, you can run npx quartz sync --help .

Most of these have sensible defaults but you can override them if you have a custom setup:
- -d or --directory : the content folder. This is normally just content
- -v or --verbose : print out extra logging information
- --commit or --no-commit : whether to make a git commit for your changes
- --push or --no-push : whether to push updates to your GitHub fork of Quartz
- --pull or --no-pull : whether to try and pull in any updates from your GitHub fork (i.e. from other devices) before pushing

Host Quartz online

quartz.jzhao.xyz • Welcome to Quartz 4