Simple second brain and [digital garden](https://jzhao.xyz/posts/digital-gardening).
## Why Quartz?
Hosting a public digital garden isn't easy. There are an overwhelming number of tutorials, resources, and guides for tools like [Notion](https://www.notion.so/), [Roam](https://roamresearch.com/), and [Obsidian](https://obsidian.md/), yet none of them have super easy to use *free* tools to publish that garden to the world.
@ -11,11 +11,11 @@ I've personally found that
> “He who works with the door open gets all kinds of interruptions, but he also occasionally gets clues as to what the world is and what might be important.” — Richard Hamming
I was really inspired by [Bianca](https://garden.bianca.digital/) and [Joel](https://joelhooks.com/digital-garden)'s digital gardens and wanted to try making my own.
**The goal of Quartz is to make hosting your own public digital garden free and simple.** You don't even need your own website. Quartz does all of that for you and gives your own little corner of the internet.
## Get Started
The entire Quartz documentation is fully hosted using Quartz! You can navigate it using the interactive Graph view below.
If you'd prefer more traditional navigation, you can also find all relevant pages through the main directory.
The entire Quartz documentation is fully hosted using Quartz! To get started, let's visit the main directory.
@ -5,11 +5,21 @@ title: "Editing Content in Quartz"
## Editing
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.
**🔗 [How to link your Obsidian Vault](notes/obsidian.md)**
Of course, all the files are in Markdown so you could just use your favourite text editor of choice, I'm not going to stop you!
### Folder Structure
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`.**
**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 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**.
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**.
```markdown
For example, I want to link this current document to `config.md`.
@ -24,44 +34,18 @@ Hugo is picky when it comes to metadata for files. Ensure that you have a title
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.
**🔗 [How to link your Obsidian Vault](notes/obsidian.md)**
Of course, all the files are in Markdown so you could just use your favourite text editor of choice, I'm not going to stop you!
## 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. For those who like to live life more on the edge, viewing the garden through Obsidian gets you pretty close to the real thing.
### 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/).
```
# Navigate to your local Quartz folder
$ cd <location-of-your-local-quartz>
# Start local server
$ hugo server
# View your site in a browser at http://localhost:1313/
```
### Install `hugo-obsidian`
This step is **doubly optional** and only applies to those who want to see their Interactive Graph and backlinks locally while previewing changes on the site.
Ensure you have Go (>= 1.16) installed.
This step will generate the list of backlinks for Hugo to parse. Ensure you have [Go](https://golang.org/doc/install) (>= 1.16) installed.
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/).
```
# Navigate to your local Quartz folder
$ cd <location-of-your-local-quartz>
# Start local server
$ hugo server
# View your site in a browser at http://localhost:1313/
```
## Publishing Changes
Now that you know the basics of managing your digital garden using Quartz, you can publish it to the internet!
@ -6,10 +6,22 @@ title: "Deploying to GitHub Pages"
## 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.
### 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!
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 essentially a `git` repository so updating it is the same workflow as you would follow as normal.
Have a fancy custom domain or want to subdomain your Quartz? That's easy too.
### 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.
Change `baseURL` in `/config.toml`. [Reference.](https://github.com/jackyzha0/quartz/blob/hugo/config.toml)
github_token: ${{ secrets.GITHUB_TOKEN }} #this can stay as is, GitHub fills this in for us!
publish_dir: ./public
publish_branch: master
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
No! Setting up Quartz means you set up a site too :)
### `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.
```
# Add the following 2 lines to your ~/.bash_profile
export GOPATH=/Users/$USER/go
export PATH=$GOPATH/bin:$PATH
# In your current terminal, to reload the session
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) to do this for you or you need to manually define it. More details in [the 'how to edit' guide](notes/editing.md).
@ -36,6 +48,6 @@ By default, the `linkIndex.yaml` (which Quartz needs to generate the Interactive
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.
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. Alternatively, you can message me on [Twitter](https://twitter.com/_jzhao) and I'll try to get back to you as soon as I can.
🐛 [Submit an Issue](https://github.com/jackyzha0/quartz/issues)
jackyzha0
3 years ago
