From 99aea4826068564f81e7f1b402e00e3e101a1476 Mon Sep 17 00:00:00 2001 From: Jacky Zhao <j.zhao2k19@gmail.com> Date: Tue, 04 Jan 2022 16:39:22 +0000 Subject: [PATCH] docs update --- content/custom Domain.md | 13 ++++++ content/notes/Obsidian.md | 10 +++-- content/notes/config.md | 1 content/notes/hosting.md | 25 +++--------- content/notes/editing.md | 19 +++++++-- content/notes/showcase.md | 0 content/notes/troubleshooting.md | 7 ++- content/notes/obsidian.md | 10 +++-- content/notes/preview changes.md | 6 +- content/_index.md | 3 + 10 files changed, 56 insertions(+), 38 deletions(-) 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 @@ ## 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) 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 `<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! \ No newline at end of file diff --git a/content/notes/Obsidian.md b/content/notes/Obsidian.md index ff2c982..e2d2cf9 100644 --- a/content/notes/Obsidian.md +++ b/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* @@ -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! \ 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 @@ ```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 @@ 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) + +``` + ### 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 @@ --- ## 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* @@ -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* -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). --- diff --git a/content/notes/obsidian.md b/content/notes/obsidian.md index ff2c982..e2d2cf9 100644 --- a/content/notes/obsidian.md +++ b/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* @@ -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! \ 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 @@ ```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 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 @@ ``` ### 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. -- Gitblit v1.10.0