docs update
This commit is contained in:
Jacky Zhao
parent
06c7923ad3
commit
fc5748ffa4
@ -12,7 +12,7 @@ Host your second brain and [digital garden](https://jzhao.xyz/posts/digital-gard
|
||||
## 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 @@ If you prefer browsing the contents of this site through a list instead of a gra
|
||||
## Troubleshooting
|
||||
- 🚧 [Troubleshooting and FAQ](notes/troubleshooting.md)
|
||||
- 🐛 [Submit an Issue](https://github.com/jackyzha0/quartz/issues)
|
||||
- 👀 [Discord Community](https://discord.gg/cRFFHYye7t)
|
||||
|
||||
13
content/custom Domain.md
Normal file
13
content/custom Domain.md
Normal 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*
|
||||
3. Wait 30 minutes to an hour for the network changes to kick in.
|
||||
4. Done!
|
||||
@ -8,15 +8,17 @@ tags:
|
||||
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*
|
||||
|
||||
@ -25,4 +27,4 @@ Inserting front matter everytime you want to create a new Note gets annoying rea
|
||||
|
||||
**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!
|
||||
@ -12,6 +12,7 @@ The majority of configuration can be be found under `data/config.yaml`. An annot
|
||||
```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
|
||||
|
||||
|
||||
@ -8,11 +8,11 @@ tags:
|
||||
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 @@ For example, I want to link this current document to `notes/config.md`.
|
||||
[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)
|
||||
|
||||
```
|
||||
|
||||
### 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)
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ tags:
|
||||
---
|
||||
|
||||
## 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 @@ By default, GitHub disables workflows from running automatically on Forked Repos
|
||||
|
||||
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*
|
||||
@ -36,10 +36,12 @@ git commit -m "message describing changes"
|
||||
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 @@ Change `cname` in `/.github/workflows/deploy.yaml`. Again, if you don't have a c
|
||||
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*
|
||||
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).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -8,15 +8,17 @@ tags:
|
||||
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*
|
||||
|
||||
@ -25,4 +27,4 @@ Inserting front matter everytime you want to create a new Note gets annoying rea
|
||||
|
||||
**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!
|
||||
@ -9,19 +9,19 @@ This step will generate the list of backlinks for Hugo to parse. Ensure you have
|
||||
|
||||
```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
|
||||
|
||||
@ -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 @@ source ~/.bash_profile
|
||||
```
|
||||
|
||||
### 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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user