ar.falsy.cat/content/notes/hosting.md

100 lines
3.6 KiB
Markdown
Raw Normal View History

---
2021-07-19 22:02:16 +00:00
title: "Deploying Quartz to the Web"
2021-12-27 02:13:21 +00:00
tags:
- setup
2022-06-30 00:03:41 +00:00
weight: -1
2022-06-30 00:34:05 +00:00
aliases:
- hosting
---
2022-06-30 00:34:05 +00:00
## Hosting on GitHub Pages
2022-01-04 16:39:22 +00:00
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.
2021-07-18 20:40:53 +00:00
### 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.
2021-07-19 04:36:15 +00:00
Head to `Settings > Action > General > Workflow Permissions` and choose `Read and Write Permissions`
![[notes/images/github-actions.png]]
*Enable GitHub Actions*
2021-07-19 04:36:15 +00:00
### Enable GitHub Pages
Head to the 'Settings' tab of your forked repository and go to the 'Pages' tab.
2022-02-17 15:44:39 +00:00
1. (IMPORTANT) Set the source to deploy from `master` (and not `hugo`) using `/ (root)`
2021-07-19 04:36:15 +00:00
2. Set a custom domain here if you have one!
2021-07-19 04:40:55 +00:00
![Enable GitHub Pages](/notes/images/github-pages.png)*Enable GitHub Pages*
2021-07-18 19:19:58 +00:00
2021-07-19 02:10:37 +00:00
### Pushing Changes
2022-02-17 15:44:39 +00:00
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.
2021-07-19 02:18:26 +00:00
```shell
# Navigate to Quartz folder
cd <path-to-quartz>
# Commit all changes
git add .
git commit -m "message describing changes"
# Push to GitHub to update site
git push origin hugo
```
2021-07-19 02:10:37 +00:00
2022-01-04 16:39:22 +00:00
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.
2021-07-19 04:36:15 +00:00
### 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.
2022-06-29 23:57:36 +00:00
Here, we take advantage of GitHub's free page hosting to deploy our site. Change `baseURL` in `/config.toml`.
2021-07-18 20:40:53 +00:00
2022-02-17 15:44:39 +00:00
Make sure that your `baseURL` has a trailing `/`!
2021-12-23 22:21:39 +00:00
[Reference `config.toml` here](https://github.com/jackyzha0/quartz/blob/hugo/config.toml)
```toml
2021-07-18 20:40:53 +00:00
baseURL = "https://<YOUR-DOMAIN>/"
```
2021-07-18 19:19:58 +00:00
2022-06-29 23:57:36 +00:00
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!**
2021-12-23 22:21:39 +00:00
```toml
baseURL = "https://<YOUR-GITHUB-USERNAME>.github.io/quartz/"
```
2021-07-19 04:36:15 +00:00
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`.
2022-02-17 15:44:39 +00:00
Please note that the `cname` field should *not* have any path `e.g. end with /quartz` or have a trailing `/`.
2021-12-23 22:21:39 +00:00
[Reference `deploy.yaml` here](https://github.com/jackyzha0/quartz/blob/hugo/.github/workflows/deploy.yaml)
2021-07-18 20:40:53 +00:00
```yaml {title=".github/workflows/deploy.yaml"}
2021-07-18 20:40:53 +00:00
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
2021-07-19 04:36:15 +00:00
github_token: ${{ secrets.GITHUB_TOKEN }} # this can stay as is, GitHub fills this in for us!
2021-07-18 20:40:53 +00:00
publish_dir: ./public
publish_branch: master
cname: <YOUR-DOMAIN>
```
2022-01-27 17:38:28 +00:00
Have a custom domain? [Learn how to set it up with Quartz ](notes/custom%20Domain.md).
2021-07-19 22:02:16 +00:00
2022-06-29 23:57:36 +00:00
### Ignoring Files
Only want to publish a subset of all of your notes? Don't worry, Quartz makes this a simple two-step process.
❌ [Excluding pages from being published](notes/ignore%20notes.md)
## 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.
2021-07-19 22:02:16 +00:00
---
2021-07-18 20:40:53 +00:00
Now that your Quartz is live, let's figure out how to make Quartz really *yours*!
2022-06-29 23:57:36 +00:00
> Step 6: 🎨 [Customizing Quartz](notes/config.md)
2021-07-18 20:40:53 +00:00
2021-12-23 22:21:39 +00:00
Having problems? Checkout our [FAQ and Troubleshooting guide](notes/troubleshooting.md).