docs: improved installation and migration guides

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
 

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
+- **[Node.js](https://nodejs.org/) v22 or later** (run `node -v` to check)
-2. **[[authoring-content|Authoring Content]]** — Write and organize your notes in the `content` folder
+- **npm v10.9.2 or later** (bundled with Node — run `npm -v` to check)
-3. **[[build|Building]]** — Preview your site locally with `npx quartz build --serve`
+- **[Git](https://git-scm.com/)** (run `git -v` to check)
-4. **[[hosting|Hosting]]** — Deploy your Quartz site to the web
+
+## 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
 

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.
+## 1. Clone Quartz
-
-![[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.
 
 ```bash
-# list all the repositories that are tracked
+git clone -b v5 https://github.com/jackyzha0/quartz.git
-git remote -v
+cd quartz
-
-# 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.
+> [!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`
+> [!note]
-> You may have an outdated version of `git`. Updating `git` should fix this issue.
+> 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`
+## 3. Initialize Your Site
-> 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
-> ```
 
-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
+```bash
-> 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:
+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

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
 

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!

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. Install dependencies
-2. **[[installation|Initialize]]** — Run `npx quartz create` to choose a template and configure your site
+npm i
-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
+# 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