docs update

Jacky Zhao

2022-01-04 99aea4826068564f81e7f1b402e00e3e101a1476

docs update

 content/_index.md

@@ -12,7 +12,7 @@
## Get Started
> 📚 [Setup your own digital garden using Quartz](notes/setup.md)

Not convinced yet? Look at some [community digital gardens](moc/showcase) built with Quartz, or read about [why I made Quartz](notes/philosophy.md) to begin with!
Not convinced yet? Look at some [community digital gardens](notes/showcase.md) built with Quartz, or read about [why I made Quartz](notes/philosophy.md) to begin with!

## Content Lists
If you prefer browsing the contents of this site through a list instead of a graph, you can find content lists here too:
@@ -23,3 +23,4 @@
## Troubleshooting
- 🚧 [Troubleshooting and FAQ](notes/troubleshooting.md)
- 🐛 [Submit an Issue](https://github.com/jackyzha0/quartz/issues)
- 👀 [Discord Community](https://discord.gg/cRFFHYye7t)

 content/custom Domain.md

New file
@@ -0,0 +1,13 @@
### Registrar
This step is only applicable if you are using a **custom domain**! If you are using a `<YOUR-USERNAME>.github.io` domain, you can skip this step.

For this last bit to take effect, you also need to create a CNAME record with the DNS provider you register your domain with (i.e. NameCheap, Google Domains).

GitHub has some [documentation on this](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site), but the tldr; is to

1. Go to your forked repository (`github.com/<YOUR-GITHUB-USERNAME>/quartz`) settings page and go to the Pages tab. Under "Custom domain", type your custom domain, then click **Save**.
2. Go to your DNS Provider and create a CNAME record that points from your domain to `<YOUR-GITHUB-USERNAME.github.io.` (yes, with the trailing period).

    ![Example Configuration for Quartz](/notes/images/google-domains.png)*Example Configuration for Quartz*
3. Wait 30 minutes to an hour for the network changes to kick in.
4. Done!

 content/notes/Obsidian.md

@@ -8,15 +8,17 @@
Obsidian is the preferred way to use Quartz. You can either create a new Obsidian Vault or link one that your already have.

### New Vault
If you don't have an existing Vault, [download Obsidian](https://obsidian.md/) and create a new Vault in the `/content` folder that you created and cloned during the [setup](notes/setup.md).
If you don't have an existing Vault, [download Obsidian](https://obsidian.md/) and create a new Vault in the `/content` folder that you created and cloned during the [setup](notes/setup.md) step.

### Linking an existing Vault
The easiest way to use an existing Vault is to copy all of our files (directory and hierarchies intact) into the `/content` folder.
The easiest way to use an existing Vault is to copy all of your files (directory and hierarchies intact) into the `/content` folder.

## Settings
Great, now that you have your Obsidian linked to your Quartz, let's fix some settings so that they play well.

Under Options > Files and Links, set the New link format to always be Absolute Path in Vault and disabled WikiLinks so Obsidian generates regular Markdown links.
1. Under Options > Files and Links, set the New link format to always be Absolute Path in Vault and disabled WikiLinks so Obsidian generates regular Markdown links.
2. Go to Settings > Files & Links > Turn "on" automatically update internal links.
3. Use [[Wikilinks]] should be off (Wikilinks are not officially supported yet)

![Obsidian Settings](/notes/images/obsidian-settings.png)*Obsidian Settings*

@@ -25,4 +27,4 @@

**If you decide to overwrite the `/content` folder completely, don't remove the `/content/templates` folder!**

Head over to Options > Core Plugins and enable the Templates plugin. Then go to Options > Hotkeys and set a hotkey for 'Insert Template'. That way, when you create a new note, you can just press the hotkey for a new template and be ready to go!
Head over to Options > Core Plugins and enable the Templates plugin. Then go to Options > Hotkeys and set a hotkey for 'Insert Template' (I recomment `[cmd]+T`). That way, when you create a new note, you can just press the hotkey for a new template and be ready to go!

 content/notes/config.md

@@ -12,6 +12,7 @@
```yaml
name: Your name here! # Shows in the footer
enableToc: true # Whether to show a Table of Contents
enableLinkPreview: true # whether to render card previews for links
description: Page description to show to search engines
page_title: Quartz Example Page # Default Page Title


 content/notes/editing.md

@@ -8,11 +8,11 @@
Quartz runs on top of [Hugo](https://gohugo.io/) so all notes are written in [Markdown](https://www.markdownguide.org/getting-started/).

### Obsidian
I *strongly* recommend using [Obsidian](http://obsidian.md/) as a way to edit and grow your digital garden. It comes with a really nice editor and graphical interface to preview all of my local files.
I recommend using [Obsidian](http://obsidian.md/) as a way to edit and grow your digital garden. It comes with a really nice editor and graphical interface to preview all of your local files.

🔗 How to link your Obsidian Vault](notes/Obsidian.md)
This step is **highly recommended**.

Of course, all the files are in Markdown so you could just use your favourite text editor of choice.
🔗 [How to setup your Obsidian Vault to work with Quartz](notes/obsidian.md)

### Ignoring Files
Only want to publish a subset of all of your notes? Don't worry, Quartz makes this a simple two-step process.
@@ -33,19 +33,28 @@
[A link to the config page](notes/config.md)
```

Similarly, you can put local images anywhere in the `/content` folder. The only caveat is that you should reference them in your Markdown by prefixing it with a `/`.

```markdown
Example image (source is in content/notes/images/example.png)
![Example Image](/content/notes/images/example.png)
```

### Front Matter
Hugo is picky when it comes to metadata for files. Make sure that your title is double-quoted and that you have a title defined at the top of your file like so:
Hugo is picky when it comes to metadata for files. Make sure that your title is double-quoted and that you have a title defined at the top of your file like so. You can also add tags here as well.

```markdown
---
title: "Example Title"
tags:
- example-tag
---

Rest of your content here...
```

## Previewing Changes
This step is purely optional and mostly for those who want to see the published version of their digital garden locally before opening it up to the internet. This is *highly recommended*.
This step is purely optional and mostly for those who want to see the published version of their digital garden locally before opening it up to the internet. This is *highly recommended* but not required.

👀 [Preview Quartz Changes](notes/preview%20changes.md)


 content/notes/hosting.md

@@ -5,7 +5,7 @@
---

## GitHub Pages
Quartz is designed to be effortless to deploy. If you forked and cloned Quartz directly from the repository, everything should already be good to go! You can head to `<YOUR-GITHUB-USERNAME.github.io/quartz` to see it live.
Quartz is designed to be effortless to deploy. If you forked and cloned Quartz directly from the repository, everything should already be good to go! Follow the steps below.

### Enable GitHub Actions
By default, GitHub disables workflows from running automatically on Forked Repostories. Head to the 'Actions' tab of your forked repository and Enable Workflows to setup deploying your Quartz site!
@@ -16,7 +16,7 @@

Head to the 'Settings' tab of your forked repository and go to the 'Pages' tab.

1. Set the source to deploy from `master` using `/ (root)`
1. (IMPORTANT) Set the source to deploy from `master` using `/ (root)`
2. Set a custom domain here if you have one!

![Enable GitHub Pages](/notes/images/github-pages.png)*Enable GitHub Pages*
@@ -36,10 +36,12 @@
git push origin hugo
```

Note: we specifically push to the `hugo` branch here. Our GitHub action automatically runs everytime a push to is detected to that branch and then updates the `master` branch for redeployment.

### Setting up the Site
Now let's get this site up and running. Never hosted a site before? No problem. Have a fancy custom domain you already own or want to subdomain your Quartz? That's easy too.

Here, we take advantage of GitHub's free page hosting to deploy our site. Change `baseURL` in `/config.toml`. If you don't have a custom domain to use, you can use `<YOUR-USERNAME>.github.io` (which GitHub gives to you for free!) as your domain.
Here, we take advantage of GitHub's free page hosting to deploy our site. Change `baseURL` in `/config.toml`.

[Reference `config.toml` here](https://github.com/jackyzha0/quartz/blob/hugo/config.toml)

@@ -67,22 +69,7 @@
    cname: <YOUR-DOMAIN>
```

### Registrar
This step is only applicable if you are using a **custom domain**! If you are using `<YOUR-USERNAME>.github.io`, you can skip this step.

For this last bit to take effect, you also need to create a CNAME record with the DNS provider you register your domain with (i.e. NameCheap, Google Domains).

GitHub has some [documentation on this](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site), but the tldr; is to

1. Go to your forked repository (`github.com/<YOUR-GITHUB-USERNAME>/quartz`) settings page and go to the Pages tab. Under "Custom domain", type your custom domain, then click **Save**.
2. Go to your DNS Provider and create a CNAME record that points from your domain to `<YOUR-GITHUB-USERNAME.github.io.` (yes, with the trailing period).

    ![Example Configuration for Quartz](/notes/images/google-domains.png)*Example Configuration for Quartz*
3. Wait 30 minutes to an hour for the network changes to kick in.
4. Done!

## External Hosting
Don't want to use GitHub Pages? Hugo builds everything for you! Everything is a packaged set of static files ready to deploy in `/public`. You can then upload this folder to a cloud provider to deploy. Alternatively, most providers also give users the option to link a GitHub repository and a folder to deploy. When doing this, ensure you select `/public` folder under the `master` branch.
Have a custom domain? [Learn how to set it up with Quartz ](custom%20Domain.md).

---


 content/notes/obsidian.md

@@ -8,15 +8,17 @@
Obsidian is the preferred way to use Quartz. You can either create a new Obsidian Vault or link one that your already have.

### New Vault
If you don't have an existing Vault, [download Obsidian](https://obsidian.md/) and create a new Vault in the `/content` folder that you created and cloned during the [setup](notes/setup.md).
If you don't have an existing Vault, [download Obsidian](https://obsidian.md/) and create a new Vault in the `/content` folder that you created and cloned during the [setup](notes/setup.md) step.

### Linking an existing Vault
The easiest way to use an existing Vault is to copy all of our files (directory and hierarchies intact) into the `/content` folder.
The easiest way to use an existing Vault is to copy all of your files (directory and hierarchies intact) into the `/content` folder.

## Settings
Great, now that you have your Obsidian linked to your Quartz, let's fix some settings so that they play well.

Under Options > Files and Links, set the New link format to always be Absolute Path in Vault and disabled WikiLinks so Obsidian generates regular Markdown links.
1. Under Options > Files and Links, set the New link format to always be Absolute Path in Vault and disabled WikiLinks so Obsidian generates regular Markdown links.
2. Go to Settings > Files & Links > Turn "on" automatically update internal links.
3. Use [[Wikilinks]] should be off (Wikilinks are not officially supported yet)

![Obsidian Settings](/notes/images/obsidian-settings.png)*Obsidian Settings*

@@ -25,4 +27,4 @@

**If you decide to overwrite the `/content` folder completely, don't remove the `/content/templates` folder!**

Head over to Options > Core Plugins and enable the Templates plugin. Then go to Options > Hotkeys and set a hotkey for 'Insert Template'. That way, when you create a new note, you can just press the hotkey for a new template and be ready to go!
Head over to Options > Core Plugins and enable the Templates plugin. Then go to Options > Hotkeys and set a hotkey for 'Insert Template' (I recomment `[cmd]+T`). That way, when you create a new note, you can just press the hotkey for a new template and be ready to go!

 content/notes/preview changes.md

@@ -9,19 +9,19 @@

```shell
# Install and link `hugo-obsidian` locally
$ go install github.com/jackyzha0/hugo-obsidian
$ go install github.com/jackyzha0/hugo-obsidian@latest

# Navigate to your local Quartz folder
$ cd <location-of-your-local-quartz>

# Scrape all links in your Quartz folder and generate info for Quartz
$ hugo-obsidian -input=content -output=data -index=true
$ hugo-obsidian -input=content -output=data -index -root=.
```

Afterwards, start the Hugo server as shown above and your local backlinks and interactive graph should be populated!

##  Installing Hugo
Hugo is the static site generator that powers Quartz. If you'd like to preview your site locally, [install Hugo](https://gohugo.io/getting-started/installing/).
Hugo is the static site generator that powers Quartz. [Install Hugo](https://gohugo.io/getting-started/installing/) first. Then,

```
# Navigate to your local Quartz folder

 content/notes/showcase.md

 content/notes/troubleshooting.md

@@ -2,7 +2,10 @@
title: "Troubleshooting and FAQ"
---

## Common Pitfalls
Still having trouble? Here are a list of common questions and problems people encounter when installing Quartz.

While you're here, join our [Discord](https://discord.gg/cRFFHYye7t) :)

### Some of my pages have 'January 1, 0001' as the last modified date
This is a problem caused by `git` treating files as case-insensitive by default and some of your posts probably have capitalized file names. You can turn this off in your Quartz by running this command.

@@ -36,7 +39,7 @@
```

### How come my notes aren't being rendered?
You probably forgot to include front matter in your Markdown files. You can either setup [Obsidian](notes/Obsidian.md) to do this for you or you need to manually define it. More details in [the 'how to edit' guide](notes/editing.md).
You probably forgot to include front matter in your Markdown files. You can either setup [obsidian](notes/obsidian.md) to do this for you or you need to manually define it. More details in [the 'how to edit' guide](notes/editing.md).

### My custom domain isn't working!
Walk through the steps in [the hosting guide](notes/hosting.md) again. Make sure you wait 30 min to 1 hour for changes to take effect.