zaine/quartz
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: improved installation and migration guides

Browse Source
This commit is contained in:
saberzero1
2026-05-21 14:33:07 +02:00
parent 47e0ba3a58
commit 0c63884f65
6 changed files with 153 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/getting-started/authoring-content.md
View File

@@ -4,11 +4,11 @@ aliases:
- "authoring content"
---
All of the content in your Quartz should go in the `/content` folder. The content for the home page of your Quartz lives in `content/index.md`. If you've [[index#🪴 Get Started|setup Quartz]] already, this folder should already be initialized. Any Markdown in this folder will get processed by Quartz.
All of the content in your Quartz should go in the `/content` folder. The content for the home page of your Quartz lives in `content/index.md`. If you've followed the [[installation|installation guide]], this folder should already be initialized. Any Markdown in this folder will get processed by Quartz.
It is recommended that you use [Obsidian](https://obsidian.md/) as a way to edit and maintain your Quartz. It comes with a nice editor and graphical interface to preview, edit, and link your local files and attachments.
Got everything setup? Let's [[build]] and preview your Quartz locally!
Got everything set up? Preview your site locally with `npx quartz build --serve`, or see the [[build|build reference]] for more options.
## Syntax
@@ -42,7 +42,7 @@ See [[Frontmatter]] for a complete list of frontmatter.
## Syncing your Content
When your Quartz is at a point you're happy with, you can save your changes to GitHub.
First, make sure you've [[installation|already setup your GitHub repository]] and then do `npx quartz sync`.
First, make sure you've [[installation#Setting Up Your GitHub Repository|set up your GitHub repository]] and then run `npx quartz sync`.
## Customization

20
docs/getting-started/index.md
View File

@@ -2,14 +2,22 @@
title: Getting Started
---
Welcome to Quartz! This section will walk you through setting up your digital garden from scratch.
This guide walks you through setting up Quartz from scratch. If you already ran the [[index#🪴 Get Started|quickstart]] on the home page, you can skip ahead to whichever step you're on.
## Setup
## Prerequisites
1. **[[installation|Installation]]** — Clone Quartz, create your repository, and push your first sync
2. **[[authoring-content|Authoring Content]]** — Write and organize your notes in the `content` folder
3. **[[build|Building]]** — Preview your site locally with `npx quartz build --serve`
4. **[[hosting|Hosting]]** — Deploy your Quartz site to the web
- **[Node.js](https://nodejs.org/) v22 or later** (run `node -v` to check)
- **npm v10.9.2 or later** (bundled with Node — run `npm -v` to check)
- **[Git](https://git-scm.com/)** (run `git -v` to check)
## Setup Steps
Follow these in order:
1. **[[installation|Installation]]** — Clone Quartz, install dependencies, run the setup wizard (`npx quartz create`), install plugins, and preview your site locally
2. **[[authoring-content|Authoring Content]]** — Write and organize your Markdown notes in the `content/` folder
3. **[[installation#Setting Up Your GitHub Repository|Push to GitHub]]** — Create a repository and push your site with `npx quartz sync`
4. **[[hosting|Deploy]]** — Host your site for free on GitHub Pages, Cloudflare, Netlify, or Vercel
## Upgrading & Migrating

133
docs/getting-started/installation.md
View File

@@ -4,55 +4,118 @@ aliases:
- "setting up your GitHub repository"
---
First, make sure you have Quartz [[index#🪴 Get Started|cloned and setup locally]].
This page walks you through the full Quartz setup: from cloning the repository to previewing your site locally, then pushing it to GitHub.
Then, create a new repository on GitHub.com. Do **not** initialize the new repository with `README`, license, or `gitignore` files.
![[github-init-repo-options.png]]
At the top of your repository on GitHub.com's Quick Setup page, click the clipboard to copy the remote repository URL.
![[github-quick-setup.png]]
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.
## 1. Clone Quartz
```bash
# 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
git clone -b v5 https://github.com/jackyzha0/quartz.git
cd quartz
```
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.
> [!note]
> Quartz 5 is currently in beta, so the default branch is still v4. The `-b v5` flag ensures you clone the right branch.
## 2. Install Dependencies
```bash
npx quartz sync --no-pull
npm i
```
> [!warning]- `fatal: --[no-]autostash option is only valid with --rebase`
> You may have an outdated version of `git`. Updating `git` should fix this issue.
> [!note]
> On subsequent clones of your own repository (e.g. on a new machine), use `npm ci` instead for a faster, reproducible install from the lockfile.
> [!warning]- `fatal: The remote end hung up unexpectedly`
> It might be due to Git's default buffer size. You can fix it by increasing the buffer with this command:
>
> ```bash
> git config http.postBuffer 524288000
> ```
## 3. Initialize Your Site
In future updates, you can simply run `npx quartz sync` every time you want to push updates to your repository.
Run the interactive setup wizard:
> [!tip] First-time plugin install on a fresh clone
> The Quartz template ships with a `quartz.lock.json` that pins community plugins to specific commits. On a brand-new clone those pins may be older than the plugins' current dependency versions, which can cause a handful of plugins to fail to build on first install. If you hit build errors during initial setup, run:
```bash
npx quartz create
```
This will prompt you for:
- A **template** (`default`, `obsidian`, `ttrpg`, `blog`) — pick the one that matches your use case. See [[create#Templates]] for details on each.
- A **content strategy** — choose how to populate the `content/` folder:
- **new**: Start with an empty folder
- **copy**: Copy files from an existing folder (e.g. your Obsidian vault)
- **symlink**: Link to an existing folder so changes sync automatically
- A **base URL** — the URL where your site will be deployed (e.g. `mysite.github.io/quartz`). Don't include `https://`.
- A **link resolution** strategy — how to resolve internal links (`shortest`, `absolute`, or `relative`). Skipped for Obsidian and TTRPG templates.
For non-interactive usage and more details, see the [[create|`quartz create` CLI reference]].
## 4. Install Plugins
The template you chose references community plugins that need to be installed:
```bash
npx quartz plugin install --from-config
```
This downloads and builds all plugins listed in `quartz.config.yaml` into `.quartz/plugins/`.
> [!tip]
> If some plugins fail to build, try refreshing them to their latest versions:
>
> ```bash
> npx quartz plugin install --latest
> ```
>
> This refreshes every plugin to the latest commit on its default branch and rewrites `quartz.lock.json`. See [[troubleshooting#Plugins fail to build on a fresh clone]] for details.
> See [[troubleshooting#Plugins fail to build on a fresh clone]] for more details.
## 5. Preview Your Site
```bash
npx quartz build --serve
```
Your site is now running at `http://localhost:8080`. The dev server watches for file changes and reloads automatically.
At this point you can [[authoring-content|start writing content]] in the `content/` folder. When you're ready to publish, continue below to push your site to GitHub and [[hosting|deploy it]].
---
## Setting Up Your GitHub Repository
To publish your site, you'll need your own GitHub repository.
### Create the Repository
Create a new repository on [GitHub.com](https://github.com/new). Do **not** initialize it with a README, license, or `.gitignore` — the Quartz clone already has these.
![[github-init-repo-options.png]]
Copy the repository URL from the Quick Setup page:
![[github-quick-setup.png]]
### Connect Your Local Clone
Point your local Quartz at your new repository:
```bash
# Check current remotes
git remote -v
# Point origin to your repository
git remote set-url origin REMOTE-URL
# Add the official Quartz repo as upstream (for future upgrades)
git remote add upstream https://github.com/jackyzha0/quartz.git
```
### Push Your Site
```bash
npx quartz sync --no-pull
```
This commits your content and pushes everything to your repository. For subsequent updates, just run:
```bash
npx quartz sync
```
> [!hint] Flags and options
> For full help options, you can run `npx quartz sync --help`.
@@ -64,3 +127,9 @@ In future updates, you can simply run `npx quartz sync` every time you want to p
> - `--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
## Next Steps
- **[[authoring-content|Authoring Content]]** — Write and organize your notes
- **[[hosting|Hosting]]** — Deploy your site to GitHub Pages, Cloudflare, Netlify, or Vercel
- **[[configuration|Configuration]]** — Customize your site's appearance and behavior

2
docs/getting-started/migrating.md
View File

@@ -7,7 +7,7 @@ aliases:
This guide covers migrating to Quartz 5 from previous versions. If you're already on Quartz 5 and want to update to the latest version, see [[upgrading|Upgrading Quartz]] instead.
If you're new to Quartz entirely, skip this guide and follow the [[installation|Installation guide]] instead.
If you're new to Quartz entirely, skip this guide and follow the [[installation|installation guide]] instead.
## Before You Start: Save Your Content

2
docs/hosting.md
View File

@@ -7,7 +7,7 @@ Quartz effectively turns your Markdown files and other resources into a bundle o
However, if you'd like to publish your site to the world, you need a way to host it online. This guide will detail how to deploy with common hosting providers but any service that allows you to deploy static HTML should work as well.
> [!warning]
> The rest of this guide assumes that you've already created your own GitHub repository for Quartz. If you haven't already, [[setting up your GitHub repository|make sure you do so]].
> The rest of this guide assumes that you've already created your own GitHub repository for Quartz. If you haven't already, follow the [[installation#Setting Up Your GitHub Repository|GitHub repository setup]] section of the installation guide.
> [!hint]
> Some Quartz features (like [[RSS Feed]] and sitemap generation) require `baseUrl` to be configured properly in your [[configuration]] to work properly. Make sure you set this before deploying!

41
docs/index.md
View File

@@ -4,26 +4,51 @@ title: Welcome to Quartz 5
Quartz is a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites. Thousands of students, developers, and teachers are [[showcase|already using Quartz]] to publish personal notes, websites, and [digital gardens](https://jzhao.xyz/posts/networked-thought) to the web.
## Getting Started
## 🪴 Get Started
Quartz requires **at least [Node](https://nodejs.org/) v22** and `npm` v10.9.2 to function correctly. Ensure you have this installed on your machine before continuing.
Quartz requires **at least [Node](https://nodejs.org/) v22** and `npm` v10.9.2 to function correctly. Ensure you have these installed on your machine before continuing.
### New to Quartz?
```shell
# 1. Clone the Quartz repository (v5 branch)
git clone -b v5 https://github.com/jackyzha0/quartz.git
cd quartz
1. **[[installation|Set up your repository]]** — Fork and clone the Quartz template
2. **[[installation|Initialize]]** — Run `npx quartz create` to choose a template and configure your site
3. **[[build|Build]]** — Preview your site locally with `npx quartz build --serve`
4. **[[hosting|Deploy]]** — Host your site for free on GitHub Pages, Cloudflare, or Netlify
# 2. Install dependencies
npm i
# 3. Initialize your site (choose a template, set your base URL, import content)
npx quartz create
# 4. Install plugins referenced by your chosen template
npx quartz plugin install --from-config
# 5. Preview your site locally
npx quartz build --serve
```
Your site is now running at `http://localhost:8080`. From here:
- **[[authoring-content|Write content]]** in the `content/` folder
- **[[installation|Push to GitHub]]** with `npx quartz sync`
- **[[hosting|Deploy]]** to GitHub Pages, Cloudflare, Netlify, or Vercel
For the full walkthrough, see the [[getting-started/index|Getting Started]] guide.
### Returning User?
If you've already set up Quartz and are cloning your repository on a new machine:
Already have a Quartz repository and cloning it on a new machine?
```shell
git clone https://github.com/<your-username>/<your-repo>.git
cd <your-repo>
npm ci
npx quartz plugin install
npx quartz build --serve
```
> [!tip]
> If you hit build errors on a fresh clone, try `npx quartz plugin install --latest` to refresh plugins to their latest versions. See [[troubleshooting#Plugins fail to build on a fresh clone]] for details.
## 🔧 Features
- [[Obsidian compatibility]], [[full-text search]], [[graph view]], [[wikilinks|wikilinks, transclusions]], [[plugins/Backlinks]], [[features/Latex|Latex]], [[syntax highlighting]], [[popover previews]], [[Docker Support]], [[i18n|internationalization]], [[features/comments|comments]] and [many more](./features/) right out of the box