From bf5a556cc15edd311cf5cb7faab2509569e6af0a Mon Sep 17 00:00:00 2001
From: Jacky Zhao <j.zhao2k19@gmail.com>
Date: Sun, 28 Jan 2024 08:20:08 +0000
Subject: [PATCH] docs: improve first-time git setup
---
docs/authoring content.md | 16 ++------
quartz/cli/handlers.js | 15 +++----
docs/setting up your GitHub repository.md | 35 +++++++++++------
docs/index.md | 3 +
4 files changed, 35 insertions(+), 34 deletions(-)
diff --git a/docs/authoring content.md b/docs/authoring content.md
index 2482140..c259e50 100644
--- a/docs/authoring content.md
+++ b/docs/authoring content.md
@@ -28,21 +28,13 @@
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 1cb02dc..cbf8719 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -23,7 +23,8 @@
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 1b5461b..43a556d 100644
--- a/docs/setting up your GitHub repository.md
+++ b/docs/setting up your GitHub repository.md
@@ -15,25 +15,34 @@
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 8e32620..b8b97b7 100644
--- a/quartz/cli/handlers.js
+++ b/quartz/cli/handlers.js
@@ -168,22 +168,20 @@
// 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 @@
// 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:
--
Gitblit v1.10.0