From dde36fa5589a362b60b7b72eb7793a3f133e159c Mon Sep 17 00:00:00 2001
From: Jacky Zhao <j.zhao2k19@gmail.com>
Date: Wed, 07 Jun 2023 17:52:53 +0000
Subject: [PATCH] update gh actions
---
content/notes/hosting.md | 66 ++++++++++++++++++++-------------
1 files changed, 40 insertions(+), 26 deletions(-)
diff --git a/content/notes/hosting.md b/content/notes/hosting.md
index c6027bb..e29f442 100644
--- a/content/notes/hosting.md
+++ b/content/notes/hosting.md
@@ -1,26 +1,34 @@
---
title: "Deploying Quartz to the Web"
+tags:
+- setup
+weight: -1
+aliases:
+- hosting
---
-## 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.
+## Hosting on 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! 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!
+### Enable GitHub Actions Permissions
+By default, GitHub disables workflows from modifying your files (for good reason!). However, Quartz needs this to write the actual site files back to GitHub.
-*Enable GitHub Actions*
+Head to `Settings > Action > General > Workflow Permissions` and choose `Read and Write Permissions`
+
+![[notes/images/github-actions.png]]
+*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)`
+1. (IMPORTANT) Set the source to deploy from `master` (and not `hugo`) using `/ (root)`
2. Set a custom domain here if you have one!
*Enable GitHub Pages*
### Pushing Changes
-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.
+To see your changes on the internet, we need to push it them to GitHub. Quartz is a `git` repository so updating it is the same workflow as you would follow as if it were just a regular software project.
```shell
# Navigate to Quartz folder
@@ -34,22 +42,34 @@
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.](https://github.com/jackyzha0/quartz/blob/hugo/config.toml)
+Make sure that your `baseURL` has a trailing `/`!
+
+[Reference `config.toml` here](https://github.com/jackyzha0/quartz/blob/hugo/config.toml)
```toml
baseURL = "https://<YOUR-DOMAIN>/"
```
+If you are using this under a subdomain (e.g. `<YOUR-GITHUB-USERNAME>.github.io/quartz`), include the trailing `/`. **You need to do this especially if you are using GitHub!**
+
+```toml
+baseURL = "https://<YOUR-GITHUB-USERNAME>.github.io/quartz/"
+```
+
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)
+Please note that the `cname` field should *not* have any path `e.g. end with /quartz` or have a trailing `/`.
-```yaml
+[Reference `deploy.yaml` here](https://github.com/jackyzha0/quartz/blob/hugo/.github/workflows/deploy.yaml)
+
+```yaml {title=".github/workflows/deploy.yaml"}
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
@@ -59,27 +79,21 @@
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.
+Have a custom domain? [Learn how to set it up with Quartz ](notes/custom%20Domain.md).
-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).
+### Ignoring Files
+Only want to publish a subset of all of your notes? Don't worry, Quartz makes this a simple two-step process.
-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
+❌ [Excluding pages from being published](notes/ignore%20notes.md)
-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.
+## Docker Support
+If you don't want to use a hosting service, you can host using [Docker](notes/docker.md) instead!
+I would *not use this method* unless you know what you are doing.
---
Now that your Quartz is live, let's figure out how to make Quartz really *yours*!
-🎨 [Customizing Quartz](notes/config.md)
+> Step 6: 🎨 [Customizing Quartz](notes/config.md)
-Having problems? Checkout our [FAQ and Troubleshooting guide](notes/troubleshooting.md).
\ No newline at end of file
+Having problems? Checkout our [FAQ and Troubleshooting guide](notes/troubleshooting.md).
--
Gitblit v1.10.0