From 388a2bf78bb08c2b37e918c3a2e0acc72803e187 Mon Sep 17 00:00:00 2001 From: Jacky Zhao Date: Thu, 17 Feb 2022 10:44:39 -0500 Subject: [PATCH] docs updates --- content/notes/editing.md | 4 ++-- content/notes/hosting.md | 10 +++++++--- content/notes/preview changes.md | 6 +++++- content/notes/troubleshooting.md | 3 +++ 4 files changed, 17 insertions(+), 6 deletions(-) diff --git a/content/notes/editing.md b/content/notes/editing.md index 17730efff..9a084c897 100644 --- a/content/notes/editing.md +++ b/content/notes/editing.md @@ -24,7 +24,7 @@ Here's a rough overview of what's what. **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 @@ 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 `/`. +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 a6725b72f..bb1d912ed 100644 --- a/content/notes/hosting.md +++ b/content/notes/hosting.md @@ -16,13 +16,13 @@ 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. (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](/notes/images/github-pages.png)*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 @@ Now let's get this site up and running. Never hosted a site before? No problem. 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:///" ``` -If you are using this under a subdomain (e.g. `.github.io/quartz`), include the trailing path. +If you are using this under a subdomain (e.g. `.github.io/quartz`), include the trailing `/`. ```toml baseURL = "https://.github.io/quartz/" @@ -57,6 +59,8 @@ baseURL = "https://.github.io/quartz/" Change `cname` in `/.github/workflows/deploy.yaml`. Again, if you don't have a custom domain to use, you can use `.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 191810eb0..8d2a38925 100644 --- a/content/notes/preview changes.md +++ b/content/notes/preview changes.md @@ -4,6 +4,8 @@ title: "Preview Changes" 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 @@ $ go install github.com/jackyzha0/hugo-obsidian@latest $ cd # 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 6aab5efc5..226216be5 100644 --- a/content/notes/troubleshooting.md +++ b/content/notes/troubleshooting.md @@ -6,6 +6,9 @@ Still having trouble? Here are a list of common questions and problems people en 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.