From bf5a556cc15edd311cf5cb7faab2509569e6af0a Mon Sep 17 00:00:00 2001 From: Jacky Zhao Date: Sun, 28 Jan 2024 00:20:08 -0800 Subject: [PATCH] docs: improve first-time git setup --- docs/authoring content.md | 16 +++-------- docs/index.md | 3 +- docs/setting up your GitHub repository.md | 35 ++++++++++++++--------- quartz/cli/handlers.js | 15 +++++----- 4 files changed, 35 insertions(+), 34 deletions(-) diff --git a/docs/authoring content.md b/docs/authoring content.md index 248214037..c259e5011 100644 --- a/docs/authoring content.md +++ b/docs/authoring content.md @@ -28,21 +28,13 @@ The rest of your content lives here. You can use **Markdown** here :) Some common frontmatter fields that are natively supported by Quartz: - `title`: Title of the page. If it isn't provided, Quartz will use the name of the file as the title. +- `description`: Description of the page used for link previews. - `aliases`: Other names for this note. This is a list of strings. +- `tags`: Tags for this note. - `draft`: Whether to publish the page or not. This is one way to make [[private pages|pages private]] in Quartz. - `date`: A string representing the day the note was published. Normally uses `YYYY-MM-DD` format. ## Syncing your Content -When your Quartz is at a point you're happy with, you can save your changes to GitHub by doing `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 +When your Quartz is at a point you're happy with, you can save your changes to GitHub. +First, make sure you've [[setting up your GitHub repository|already setup your GitHub repository]] and then do `npx quartz sync`. diff --git a/docs/index.md b/docs/index.md index 1cb02dc95..cbf8719d1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -23,7 +23,8 @@ This will guide you through initializing your Quartz with content. Once you've d 2. [[configuration|Configure]] Quartz's behaviour 3. Change Quartz's [[layout]] 4. [[build|Build and preview]] Quartz -5. [[hosting|Host]] Quartz online +5. Sync your changes with [[setting up your GitHub repository|GitHub]] +6. [[hosting|Host]] Quartz online If you prefer instructions in a video format you can try following Nicole van der Hoeven's [video guide on how to set up Quartz!](https://www.youtube.com/watch?v=6s6DT1yN4dw&t=227s) diff --git a/docs/setting up your GitHub repository.md b/docs/setting up your GitHub repository.md index 1b5461b51..43a556dc1 100644 --- a/docs/setting up your GitHub repository.md +++ b/docs/setting up your GitHub repository.md @@ -15,25 +15,34 @@ At the top of your repository on GitHub.com's Quick Setup page, click the clipb 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 -# add your repository -git remote add origin REMOTE-URL +# list all the repositories that are tracked +git remote -v -# track the main quartz repository for updates +# 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 ``` -To verify that you set the remote URL correctly, run the following command. - -```bash -git remote -v -``` - -Then, you can sync the content to upload it to your repository. +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. ```bash npx quartz sync --no-pull ``` -> [!hint] -> If `npx quartz sync` fails with `fatal: --[no-]autostash option is only valid with --rebase`, you -> may have an outdated version of `git`. Updating `git` should fix this issue. +> [!warning]- `fatal: --[no-]autostash option is only valid with --rebase` +> You may have an outdated version of `git`. Updating `git` should fix this issue. + +In future updates, you can simply run `npx quartz sync` every time you want to push updates to your repository. + +> [!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 diff --git a/quartz/cli/handlers.js b/quartz/cli/handlers.js index 8e32620b3..b8b97b721 100644 --- a/quartz/cli/handlers.js +++ b/quartz/cli/handlers.js @@ -168,22 +168,20 @@ See the [documentation](https://quartz.jzhao.xyz) for how to get started. // get a preferred link resolution strategy linkResolutionStrategy = exitIfCancel( await select({ - message: `Choose how Quartz should resolve links in your content. You can change this later in \`quartz.config.ts\`.`, + message: `Choose how Quartz should resolve links in your content. This should match Obsidian's link format. You can change this later in \`quartz.config.ts\`.`, options: [ - { - value: "absolute", - label: "Treat links as absolute path", - hint: "for content made for Quartz 3 and Hugo", - }, { value: "shortest", label: "Treat links as shortest path", - hint: "for most Obsidian vaults", + hint: "(default)", + }, + { + value: "absolute", + label: "Treat links as absolute path", }, { value: "relative", label: "Treat links as relative paths", - hint: "for just normal Markdown files", }, ], }), @@ -202,6 +200,7 @@ See the [documentation](https://quartz.jzhao.xyz) for how to get started. // setup remote execSync( `git remote show upstream || git remote add upstream https://github.com/jackyzha0/quartz.git`, + { stdio: "ignore" }, ) outro(`You're all set! Not sure what to do next? Try: