docs: improve first-time git setup

This commit is contained in:
Jacky Zhao 2024-01-28 00:20:08 -08:00
parent c4b756c817
commit bf5a556cc1
4 changed files with 35 additions and 34 deletions

View file

@ -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: 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. - `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. - `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. - `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. - `date`: A string representing the day the note was published. Normally uses `YYYY-MM-DD` format.
## Syncing your Content ## 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`. 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`.
> [!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

View file

@ -23,7 +23,8 @@ This will guide you through initializing your Quartz with content. Once you've d
2. [[configuration|Configure]] Quartz's behaviour 2. [[configuration|Configure]] Quartz's behaviour
3. Change Quartz's [[layout]] 3. Change Quartz's [[layout]]
4. [[build|Build and preview]] Quartz 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 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) [video guide on how to set up Quartz!](https://www.youtube.com/watch?v=6s6DT1yN4dw&t=227s)

View file

@ -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. 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 ```bash
# add your repository # list all the repositories that are tracked
git remote add origin REMOTE-URL 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 git remote add upstream https://github.com/jackyzha0/quartz.git
``` ```
To verify that you set the remote URL correctly, run the following command. 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
git remote -v
```
Then, you can sync the content to upload it to your repository.
```bash ```bash
npx quartz sync --no-pull npx quartz sync --no-pull
``` ```
> [!hint] > [!warning]- `fatal: --[no-]autostash option is only valid with --rebase`
> If `npx quartz sync` fails with `fatal: --[no-]autostash option is only valid with --rebase`, you > You may have an outdated version of `git`. Updating `git` should fix this issue.
> 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

View file

@ -168,22 +168,20 @@ See the [documentation](https://quartz.jzhao.xyz) for how to get started.
// get a preferred link resolution strategy // get a preferred link resolution strategy
linkResolutionStrategy = exitIfCancel( linkResolutionStrategy = exitIfCancel(
await select({ 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: [ options: [
{
value: "absolute",
label: "Treat links as absolute path",
hint: "for content made for Quartz 3 and Hugo",
},
{ {
value: "shortest", value: "shortest",
label: "Treat links as shortest path", label: "Treat links as shortest path",
hint: "for most Obsidian vaults", hint: "(default)",
},
{
value: "absolute",
label: "Treat links as absolute path",
}, },
{ {
value: "relative", value: "relative",
label: "Treat links as relative paths", 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 // setup remote
execSync( execSync(
`git remote show upstream || git remote add upstream https://github.com/jackyzha0/quartz.git`, `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: outro(`You're all set! Not sure what to do next? Try: