From 69e42886a6a7e094577618f4b37c6dde3b540c1d Mon Sep 17 00:00:00 2001
From: jackyzha0 <j.zhao2k19@gmail.com>
Date: Sun, 18 Jul 2021 20:40:53 +0000
Subject: [PATCH] flesh out docs
---
content/notes/config.md | 43 +++++++++++++-
content/notes/hosting.md | 43 +++++++++++++-
data/graphConfig.yaml | 6 --
content/notes/editing.md | 14 ++++
content/moc/showcase.md | 10 +++
content/notes/images/google-domains.png | 0
content/notes/troubleshooting.md | 35 +++++++++++
content/notes/obsidian.md | 22 ++++++-
content/moc/directory.md | 2
9 files changed, 158 insertions(+), 17 deletions(-)
diff --git a/content/moc/directory.md b/content/moc/directory.md
index 7726de8..039fd81 100644
--- a/content/moc/directory.md
+++ b/content/moc/directory.md
@@ -12,6 +12,8 @@
- 🎨 [Customizing and Styling Quartz](notes/config.md)
- 🌍 [Hosting Quartz online!](notes/hosting.md)
+Not convinced yet? Look at some [cool digital gardens](moc/showcase)
+
## Troubleshooting
- 🚧 [Troubleshooting and FAQ](notes/troubleshooting.md)
- 🐛 [Submit an Issue](https://github.com/jackyzha0/quartz/issues)
\ No newline at end of file
diff --git a/content/moc/showcase.md b/content/moc/showcase.md
new file mode 100644
index 0000000..3c2a0b4
--- /dev/null
+++ b/content/moc/showcase.md
@@ -0,0 +1,10 @@
+---
+title: "Showcase"
+---
+
+Want to see what Quartz can do? Here are some cool community gardens :)
+
+- [Quartz Documentation (this site!)](https://quartz.jzhao.xyz/)
+- [Jacky Zhao's Garden](https://jzhao.xyz/toc/directory/)
+
+If you want to see your own on here, submit a [Pull Request adding yourself to this file](https://github.com/jackyzha0/quartz/blob/hugo/content/moc/showcase.md)!
\ No newline at end of file
diff --git a/content/notes/config.md b/content/notes/config.md
index 89e7d8d..f701473 100644
--- a/content/notes/config.md
+++ b/content/notes/config.md
@@ -2,7 +2,44 @@
title: "Configuration"
---
+## Configuration
+Quartz is designed to be extremely configurable. You can find the bulk of the configuration scattered throughout the repository depending on how in-depth you'd like to get.
+
+The majority of configuration can be be found under `data/config.yaml`. An annotated example configuration is shown below.
+
+```yaml
+name: Your name here! # Shows in the footer
+enableToc: true # Whether to show a Table of Contents
+description: Page description to show to search engines
+page_title: Quartz Example Page # Default Page Title
+
+links: # Links to show in footer
+ - link_name: Twitter
+ link: https://twitter.com/_jzhao
+ - link_name: Github
+ link: https://github.com/jackyzha0
+```
+
+### Graph View
+To customize the Interactive Graph view, you can poke around `data/graphConfig.yaml`.
+
+```yaml
+enableLegend: false # automatically generate a legend
+enableDrag: true # allow dragging nodes in the graph
+enableZoom: true # allow zooming and panning the graph
+paths: # colour specific nodes path off of their path
+ - /moc: "#4388cc"
+```
+
+
## Styling
-## Layouts
-### Home Page
-### Partials
\ No newline at end of file
+Want to go even more in-depth? You can add custom CSS styling and change existing colours through editing `assets/custom.scss`. If you'd like to target specific parts of the site, you can add ids and classes to the HTML partials in `/layouts/partials`.
+
+### Partials
+Partials are what dictate what actually gets rendered to the page. Want to change how pages are styled and structured? You can edit the appropriate layout in `/layouts`.
+
+For example, the structure of the home page can be edited through `/layouts/index.html`. To customize the footer, you can edit `/layouts/partials/footer.html`
+
+More info about partials on [Hugo's website.](https://gohugo.io/templates/partials/)
+
+Still having problems? Checkout our [FAQ and Troubleshooting guide](notes/troubleshooting.md).
\ No newline at end of file
diff --git a/content/notes/editing.md b/content/notes/editing.md
index 3264d4b..6b47767 100644
--- a/content/notes/editing.md
+++ b/content/notes/editing.md
@@ -7,6 +7,8 @@
**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`.**
+
To create a link, 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**.
```markdown
@@ -14,6 +16,18 @@
[A link to the config page](config.md)
```
+### Front Matter
+Hugo is picky when it comes to metadata for files. Ensure that you have a title defined at the top of your file like so:
+
+```markdown
+---
+title: "Example Title"
+---
+
+## Headers should start at H2
+Rest of your content here...
+```
+
### 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.
diff --git a/content/notes/hosting.md b/content/notes/hosting.md
index 18717f8..8ddaf1c 100644
--- a/content/notes/hosting.md
+++ b/content/notes/hosting.md
@@ -2,13 +2,48 @@
title: "Deploying to GitHub Pages"
---
-## GitHub Pages
-## Custom subdomain
-Change `baseURL` in `/config.toml`
+## 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.
+
+By default, Github Actions will run on forks of repos. You should not need to do any more config to see it up to date.
+
+### Custom subdomain
+Have a fancy custom domain or want to subdomain your Quartz? That's easy too.
+
+Change `baseURL` in `/config.toml`. [Reference.](https://github.com/jackyzha0/quartz/blob/hugo/config.toml)
```toml
-baseURL = "https://quartz.jzhao.xyz/"
+baseURL = "https://<YOUR-DOMAIN>/"
```
+Change `cname` in `/.github/workflows/deploy.yaml`. [Reference.](https://github.com/jackyzha0/quartz/blob/hugo/.github/workflows/deploy.yaml)
+
+```yaml
+- name: Deploy
+ uses: peaceiris/actions-gh-pages@v3
+ with:
+ github_token: ${{ secrets.GITHUB_TOKEN }}
+ publish_dir: ./public
+ publish_branch: master
+ cname: <YOUR-DOMAIN>
+```
+
+### Registrar
+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!
+
+
+Now that your Quartz is live, let's figure out how to make Quartz really *yours*!
+
+🎨 [Customizing Quarts](notes/config.md)
+
Having problems? Checkout our [FAQ and Troubleshooting guide](notes/troubleshooting.md).
\ No newline at end of file
diff --git a/content/notes/images/google-domains.png b/content/notes/images/google-domains.png
new file mode 100644
index 0000000..a438269
--- /dev/null
+++ b/content/notes/images/google-domains.png
Binary files differ
diff --git a/content/notes/obsidian.md b/content/notes/obsidian.md
index bd4eb02..52931ca 100644
--- a/content/notes/obsidian.md
+++ b/content/notes/obsidian.md
@@ -2,11 +2,25 @@
title: "Obsidian Vault Integration"
---
+## Setup
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
+### 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).
-## Linking an existing Vault
+### 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.
-
\ No newline at end of file
+## 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.
+
+*Obsidian Settings*
+
+## Templates
+Inserting front matter everytime you want to create a new Note gets really annoying really quickly. Luckily, Obsidian supports templates which makes inserting new content really easily.
+
+**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
diff --git a/content/notes/troubleshooting.md b/content/notes/troubleshooting.md
index 8a986b1..db3da72 100644
--- a/content/notes/troubleshooting.md
+++ b/content/notes/troubleshooting.md
@@ -1,3 +1,38 @@
---
title: "Troubleshooting and FAQ"
---
+
+## Common Pitfalls
+### 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) 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.
+
+### How do I setup Google Analytics?
+You can edit it in `config.toml` and either use a V3 (UA-) or V4 (G-) tag.
+
+### How do I change the content on the home page?
+To edit the main home page, open `/content/_index.md`.
+
+### How do I change the colours?
+You can change the theme by editing `assets/custom.scss`. More details on customization and themeing can be found in the [customization guide](notes/config.md).
+
+### How do I add images?
+You can put 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)
+
+```
+
+### My Interactive Graph and Backlinks aren't up to date
+By default, the `linkIndex.yaml` (which Quartz needs to generate the Interactive Graph and Backlinks) are not regenerated locally. To set that up, see the guide on [local editing](notes/editing.md)
+
+### Can I use React/Vue/some other framework?
+Not out of the box. You could probably make it work by editing `/layouts/_default/single.html` but that's not what Quartz is designed to work with. 99% of things you are trying to do with those frameworks you can accomplish perfectly fine using just vanilla HTML/CSS/JS.
+
+## Still Stuck?
+Quartz isn't perfect! If you're still having troubles, file an issue in the GitHub repo with as much information as you can reasonably provide.
+
+🐛 [Submit an Issue](https://github.com/jackyzha0/quartz/issues)
\ No newline at end of file
diff --git a/data/graphConfig.yaml b/data/graphConfig.yaml
index 67f481b..4104e42 100644
--- a/data/graphConfig.yaml
+++ b/data/graphConfig.yaml
@@ -1,11 +1,5 @@
enableLegend: false
enableDrag: true
enableZoom: true
-base:
- node: "#284b63"
- activeNode: "#f28482"
- inactiveNode: "#a8b3bd"
- link: "#babdbf"
- activeLink: "#5a7282"
paths:
- /moc: "#4388cc"
\ No newline at end of file
--
Gitblit v1.10.0