Initial commit

docs/getting-started/installation.md

@@ -0,0 +1,161 @@
+---
+title: "Installation"
+aliases:
+  - "setting up your GitHub repository"
+---
+
+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. 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]
+> Quartz requires **Node.js 22** or later. Check your version with `node -v` and upgrade at [nodejs.org](https://nodejs.org/) if needed.
+
+```bash
+npm i
+```
+
+> [!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.
+
+## 3. Initialize Your Site
+
+Run the interactive setup wizard:
+
+```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
+> ```
+>
+> 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
+
+> [!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` — Quartz already includes these files, and duplicating them will cause merge conflicts on your first push.
+
+![[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
+```
+
+> [!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
+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`.
+>
+> Most of these have sensible defaults but you can override them if you have a custom setup:
+>
+> - `-d` or `--directory`: the content folder. This is normally just `content`
+> - `-v` or `--verbose`: print out extra logging information
+> - `--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