From 0c63884f65d38212039faaa4180ec6e576f23234 Mon Sep 17 00:00:00 2001 From: saberzero1 Date: Thu, 21 May 2026 14:33:07 +0200 Subject: [PATCH] docs: improved installation and migration guides --- docs/getting-started/authoring-content.md | 6 +- docs/getting-started/index.md | 20 +++- docs/getting-started/installation.md | 133 ++++++++++++++++------ docs/getting-started/migrating.md | 2 +- docs/hosting.md | 2 +- docs/index.md | 41 +++++-- 6 files changed, 153 insertions(+), 51 deletions(-) diff --git a/docs/getting-started/authoring-content.md b/docs/getting-started/authoring-content.md index ce30ae1..088d025 100644 --- a/docs/getting-started/authoring-content.md +++ b/docs/getting-started/authoring-content.md @@ -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 diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 967a1bc..d1ed739 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -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 diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index bfbc10c..96cc137 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -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 diff --git a/docs/getting-started/migrating.md b/docs/getting-started/migrating.md index e7e63ac..3779bfc 100644 --- a/docs/getting-started/migrating.md +++ b/docs/getting-started/migrating.md @@ -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 diff --git a/docs/hosting.md b/docs/hosting.md index 3b4947d..0ca5f6b 100644 --- a/docs/hosting.md +++ b/docs/hosting.md @@ -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! diff --git a/docs/index.md b/docs/index.md index eba3fd8..45250da 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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//.git +cd +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