diff --git a/content/_index.md b/content/_index.md index 4b44062..c24bd6f 100644 --- a/content/_index.md +++ b/content/_index.md @@ -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) \ No newline at end of file diff --git a/content/notes/editing.md b/content/notes/editing.md index 6b47767..2cb9572 100644 --- a/content/notes/editing.md +++ b/content/notes/editing.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 + +# 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 - -# 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! diff --git a/content/notes/hosting.md b/content/notes/hosting.md index 3186567..4a5a06b 100644 --- a/content/notes/hosting.md +++ b/content/notes/hosting.md @@ -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 `.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:///" ``` -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 `.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: ``` ### 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 diff --git a/content/notes/images/github-actions.png b/content/notes/images/github-actions.png new file mode 100644 index 0000000..8e977cb Binary files /dev/null and b/content/notes/images/github-actions.png differ diff --git a/content/notes/images/github-pages.png b/content/notes/images/github-pages.png new file mode 100644 index 0000000..2c606f5 Binary files /dev/null and b/content/notes/images/github-pages.png differ diff --git a/content/notes/troubleshooting.md b/content/notes/troubleshooting.md index fe0c972..7d508c6 100644 --- a/content/notes/troubleshooting.md +++ b/content/notes/troubleshooting.md @@ -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) \ No newline at end of file