From 9e74db69a9bb71079cfd72452db1cae720139766 Mon Sep 17 00:00:00 2001 From: saberzero1 Date: Thu, 11 Jun 2026 15:07:26 +0200 Subject: [PATCH] docs: clarified and extended installation guide --- docs/getting-started/index.md | 10 ++++++- docs/getting-started/installation.md | 40 +++++++++++++++++++++++----- docs/index.md | 5 +++- 3 files changed, 46 insertions(+), 9 deletions(-) diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 4a55a19..37e5eb6 100644 --- a/docs/getting-started/index.md +++ b/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 diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index bba37b4..b07ba45 100644 --- a/docs/getting-started/installation.md +++ b/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//.git +cd +``` + +### 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 diff --git a/docs/index.md b/docs/index.md index f3e5952..5353074 100644 --- a/docs/index.md +++ b/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