docs: clarified and extended installation guide

docs/getting-started/index.md

@@ -6,15 +6,23 @@ This guide walks you through setting up Quartz from scratch. If you already ran
 
 ## Prerequisites
 
+You need these tools installed before continuing:
+
 - **[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)
 
+> [!warning] Common issues
+>
+> - **Linux**: System packages (`apt install nodejs`) often ship much older versions. Use [nvm](https://github.com/nvm-sh/nvm) or the [NodeSource](https://github.com/nodesource/distributions) repository to get Node.js v22.
+> - **Windows**: When installing Git, make sure **"Git from the command line and also from 3rd-party software"** is selected so that `git` is available in your terminal. If `node -v` or `git -v` shows "command not found", restart your terminal or check your PATH.
+> - **macOS**: The Xcode command-line tools include Git (`xcode-select --install`). For Node.js, [nvm](https://github.com/nvm-sh/nvm) or the [official installer](https://nodejs.org/) both work.
+
 ## 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
+1. **[[installation|Installation]]** — Get Quartz (via GitHub template or clone), 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

docs/getting-started/installation.md

@@ -4,15 +4,38 @@ aliases:
   - "setting up your GitHub repository"
 ---
 
-This page walks you through the full Quartz setup: from cloning the repository to previewing your site locally, then pushing it to GitHub.
+This page walks you through the full Quartz setup: from getting the source code to previewing your site locally, then pushing it to GitHub.
 
-## 1. Clone Quartz
+## 1. Get Quartz
+
+There are two ways to get started. Pick whichever you prefer:
+
+### Option A: Use the GitHub Template (Recommended)
+
+> [!tip] Why this option?
+> Using the template creates your own repository in one click — no need to reconfigure Git remotes later.
+
+1. Go to the [Quartz repository](https://github.com/jackyzha0/quartz) and click **Use this template** → **Create a new repository**
+2. Give your repository a name (e.g. `quartz`, `notes`, `garden`), choose public or private, then click **Create repository**
+3. Clone **your new repository** and enter the folder:
+
+```bash
+git clone https://github.com/<your-username>/<your-repo>.git
+cd <your-repo>
+```
+
+### Option B: Clone Directly
+
+If you don't use GitHub or prefer a manual setup:
 
 ```bash
 git clone https://github.com/jackyzha0/quartz.git
 cd quartz
 ```
 
+> [!note]
+> With this option, you'll need to [[#Connect Your Local Clone|point the `origin` remote]] to your own repository later when you're ready to publish.
+
 ## 2. Install Dependencies
 
 > [!important]
@@ -78,11 +101,14 @@ At this point you can [[authoring-content|start writing content]] in the `conten
 
 ## Setting Up Your GitHub Repository
 
-To publish your site, you'll need your own GitHub repository.
+> [!note]
+> If you used **Option A** (GitHub Template) in step 1, your repository already exists and `origin` is already set. You can skip straight to [[#Push Your Site]].
+
+To publish your site, you'll need your own GitHub repository. This section is for **Option B** (direct clone) users.
 
 ### 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.
+Create a new repository on [GitHub.com](https://github.com/new). Do **not** initialize it with a README, license, or `.gitignore` — Quartz already includes these files, and duplicating them will cause merge conflicts on your first push.
 
 ![[github-init-repo-options.png]]
 
@@ -100,11 +126,11 @@ 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
 ```
 
+> [!tip]
+> You don't need to add an `upstream` remote manually — `npx quartz create` already configured it for you. The upstream remote is used by `npx quartz upgrade` to pull in future Quartz updates.
+
 ### Push Your Site
 
 ```bash

docs/index.md

@@ -6,7 +6,10 @@ Quartz is a fast, batteries-included static-site generator that transforms Markd
 
 ## 🪴 Get Started
 
-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.
+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. See the [[getting-started/index#Prerequisites|prerequisites]] for help installing them.
+
+> [!tip] GitHub users
+> You can also use the **[GitHub template](https://github.com/jackyzha0/quartz/generate)** to create your repository in one click, then clone that instead. See [[installation#Option A Use the GitHub Template Recommended|Option A]] in the installation guide.
 
 ```shell
 # 1. Clone the Quartz repository