From 388a2bf78bb08c2b37e918c3a2e0acc72803e187 Mon Sep 17 00:00:00 2001 From: Jacky Zhao <j.zhao2k19@gmail.com> Date: Thu, 17 Feb 2022 15:44:39 +0000 Subject: [PATCH] docs updates --- content/notes/hosting.md | 10 +++++++--- content/notes/editing.md | 4 ++-- content/notes/troubleshooting.md | 3 +++ content/notes/preview changes.md | 6 +++++- 4 files changed, 17 insertions(+), 6 deletions(-) diff --git a/content/notes/editing.md b/content/notes/editing.md index 17730ef..9a084c8 100644 --- a/content/notes/editing.md +++ b/content/notes/editing.md @@ -24,7 +24,7 @@ **All content in your garden can found in the `/content` folder.** To make edits, you can open any of the files and make changes directly and save it. You can organize content into any folder you'd like. -**To edit the main home page, open `/content/_index.md`.** This is the home page which is slightly special. You don't need front matter here! +**To edit the main home page, open `/content/_index.md`.* To create a link between notes in your garden, just create a normal link using Markdown pointing to the document in question. Please note that **all links should be relative to the root `/content` path**. @@ -33,7 +33,7 @@ [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 `/`. +Similarly, you can put local images anywhere in the `/content` folder. ```markdown Example image (source is in content/notes/images/example.png) diff --git a/content/notes/hosting.md b/content/notes/hosting.md index a6725b7..bb1d912 100644 --- a/content/notes/hosting.md +++ b/content/notes/hosting.md @@ -16,13 +16,13 @@ Head to the 'Settings' tab of your forked repository and go to the 'Pages' tab. -1. (IMPORTANT) Set the source to deploy from `master` using `/ (root)` +1. (IMPORTANT) Set the source to deploy from `master` (and not `hugo`) using `/ (root)` 2. Set a custom domain here if you have one! *Enable GitHub Pages* ### Pushing Changes -To see your changes on the internet, we need to push it them to GitHub. Quartz is essentially a `git` repository so updating it is the same workflow as you would follow as normal. +To see your changes on the internet, we need to push it them to GitHub. Quartz is a `git` repository so updating it is the same workflow as you would follow as if it were just a regular software project. ```shell # Navigate to Quartz folder @@ -43,13 +43,15 @@ Here, we take advantage of GitHub's free page hosting to deploy our site. Change `baseURL` in `/config.toml`. +Make sure that your `baseURL` has a trailing `/`! + [Reference `config.toml` here](https://github.com/jackyzha0/quartz/blob/hugo/config.toml) ```toml baseURL = "https://<YOUR-DOMAIN>/" ``` -If you are using this under a subdomain (e.g. `<YOUR-GITHUB-USERNAME>.github.io/quartz`), include the trailing path. +If you are using this under a subdomain (e.g. `<YOUR-GITHUB-USERNAME>.github.io/quartz`), include the trailing `/`. ```toml baseURL = "https://<YOUR-GITHUB-USERNAME>.github.io/quartz/" @@ -57,6 +59,8 @@ Change `cname` in `/.github/workflows/deploy.yaml`. Again, if you don't have a custom domain to use, you can use `<YOUR-USERNAME>.github.io`. +Please note that the `cname` field should *not* have any path `e.g. end with /quartz` or have a trailing `/`. + [Reference `deploy.yaml` here](https://github.com/jackyzha0/quartz/blob/hugo/.github/workflows/deploy.yaml) ```yaml diff --git a/content/notes/preview changes.md b/content/notes/preview changes.md index 191810e..8d2a389 100644 --- a/content/notes/preview changes.md +++ b/content/notes/preview changes.md @@ -4,6 +4,8 @@ If you'd like to preview what your Quartz site looks like before deploying it to the internet, here's exactly how to do that! +Note that both of these steps need to be completed. + ## Install `hugo-obsidian` This step will generate the list of backlinks for Hugo to parse. Ensure you have [Go](https://golang.org/doc/install) (>= 1.16) installed. @@ -15,9 +17,11 @@ $ 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 -root=. +$ hugo-obsidian -input=content -output=static -index -root=. ``` +If you are running into an error saying that `command not found: hugo-obsidian`, make sure you set your `GOPATH` correctly! This will allow your terminal to correctly recognize hugo-obsidian as an executable. + Afterwards, start the Hugo server as shown above and your local backlinks and interactive graph should be populated! ## Installing Hugo diff --git a/content/notes/troubleshooting.md b/content/notes/troubleshooting.md index 6aab5ef..226216b 100644 --- a/content/notes/troubleshooting.md +++ b/content/notes/troubleshooting.md @@ -6,6 +6,9 @@ While you're here, join our [Discord](https://discord.gg/cRFFHYye7t) :) +### My GitHub pages is just showing the README and not Quartz +Make sure you set the source to deploy from `master` (and not `hugo`) using `/ (root)`! See more in the [hosting](/notes/hosting) guide + ### 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. -- Gitblit v1.10.0