more desc
This commit is contained in:
jackyzha0
parent
b841471613
commit
c0ee39a937
|
|
@ -1,5 +1,5 @@
|
|||
# 🌱 Quartz
|
||||
Simple second brain and digital garden.
|
||||
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.
|
||||
|
||||
👉 [Directory](moc/directory.md)
|
||||
|
|
@ -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,20 +34,28 @@ 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.
|
||||
|
||||
### 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.
|
||||
|
||||
```shell
|
||||
# Install and link `hugo-obsidian` locally
|
||||
$ go install github.com/jackyzha0/hugo-obsidian
|
||||
|
||||
# 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
|
||||
```
|
||||
|
||||
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/).
|
||||
|
||||
|
|
@ -51,27 +69,6 @@ $ 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.
|
||||
|
||||
```shell
|
||||
# Clone the Repository
|
||||
$ git clone https://github.com/jackyzha0/hugo-obsidian.git
|
||||
|
||||
# Install and link `hugo-obsidian` locally
|
||||
$ go install .
|
||||
|
||||
# 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
|
||||
```
|
||||
|
||||
Afterwards, start the Hugo server as shown above and your local backlinks and interactive graph should be populated!
|
||||
|
||||
## 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!
|
||||
|
||||
*Enable GitHub Actions*
|
||||
|
||||
### Enable GitHub Pages
|
||||
|
||||
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)`
|
||||
2. Set a custom domain here if you have one!
|
||||
|
||||
*Enable GitHub Pages*
|
||||
|
||||
### Pushing Changes
|
||||
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.
|
||||
|
||||
```shell
|
||||
# Navigate to Quartz folder
|
||||
|
|
@ -23,28 +35,34 @@ git commit -m "message describing changes"
|
|||
git push origin hugo
|
||||
```
|
||||
|
||||
### Custom subdomain
|
||||
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.
|
||||
|
||||
Change `baseURL` in `/config.toml`. [Reference.](https://github.com/jackyzha0/quartz/blob/hugo/config.toml)
|
||||
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.
|
||||
|
||||
[Reference.](https://github.com/jackyzha0/quartz/blob/hugo/config.toml)
|
||||
|
||||
```toml
|
||||
baseURL = "https://<YOUR-DOMAIN>/"
|
||||
```
|
||||
|
||||
Change `cname` in `/.github/workflows/deploy.yaml`. [Reference.](https://github.com/jackyzha0/quartz/blob/hugo/.github/workflows/deploy.yaml)
|
||||
Change `cname` in `/.github/workflows/deploy.yaml`. Again, if you don't have a custom domain to use, you can use `<YOUR-USERNAME>.github.io`.
|
||||
|
||||
[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 }}
|
||||
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
|
||||
|
|
|
|||
Binary file not shown.
|
After Width: | Height: | Size: 116 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 226 KiB |
|
|
@ -6,6 +6,18 @@ title: "Troubleshooting and FAQ"
|
|||
### Do I need a website already?
|
||||
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)
|
||||
Loading…
Reference in New Issue