From 99aea4826068564f81e7f1b402e00e3e101a1476 Mon Sep 17 00:00:00 2001 From: Jacky Zhao Date: Tue, 4 Jan 2022 11:39:22 -0500 Subject: [PATCH] docs update --- content/_index.md | 3 ++- content/custom Domain.md | 13 +++++++++++++ content/notes/Obsidian.md | 10 ++++++---- content/notes/config.md | 1 + content/notes/editing.md | 19 ++++++++++++++----- content/notes/hosting.md | 25 ++++++------------------- content/notes/obsidian.md | 10 ++++++---- content/notes/preview changes.md | 6 +++--- content/{moc => notes}/showcase.md | 0 content/notes/troubleshooting.md | 7 +++++-- 10 files changed, 56 insertions(+), 38 deletions(-) create mode 100644 content/custom Domain.md rename content/{moc => notes}/showcase.md (100%) diff --git a/content/_index.md b/content/_index.md index 9bc9781..cc1f732 100644 --- a/content/_index.md +++ b/content/_index.md @@ -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) diff --git a/content/custom Domain.md b/content/custom Domain.md new file mode 100644 index 0000000..93a6b9e --- /dev/null +++ b/content/custom Domain.md @@ -0,0 +1,13 @@ +### Registrar +This step is only applicable if you are using a **custom domain**! If you are using a `.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//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 ` 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 @@ 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! \ No newline at end of file +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! \ No newline at end of file diff --git a/content/notes/config.md b/content/notes/config.md index a5c194f..8de7de6 100644 --- a/content/notes/config.md +++ b/content/notes/config.md @@ -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 diff --git a/content/notes/editing.md b/content/notes/editing.md index e53fcc7..a9d7290 100644 --- a/content/notes/editing.md +++ b/content/notes/editing.md @@ -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) +![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) diff --git a/content/notes/hosting.md b/content/notes/hosting.md index 9e26ad2..b474652 100644 --- a/content/notes/hosting.md +++ b/content/notes/hosting.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 `.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: ``` -### Registrar -This step is only applicable if you are using a **custom domain**! If you are using `.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//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 ` 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 @@ 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! \ No newline at end of file +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! \ No newline at end of file diff --git a/content/notes/preview changes.md b/content/notes/preview changes.md index dac619e..45f60f3 100644 --- a/content/notes/preview changes.md +++ b/content/notes/preview changes.md @@ -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 # 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 diff --git a/content/moc/showcase.md b/content/notes/showcase.md similarity index 100% rename from content/moc/showcase.md rename to content/notes/showcase.md diff --git a/content/notes/troubleshooting.md b/content/notes/troubleshooting.md index 0330fed..6aab5ef 100644 --- a/content/notes/troubleshooting.md +++ b/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 @@ 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.