| | |
|---|
| | | --- |
|---|
| | | title: "Deploying to GitHub Pages" |
|---|
| | | title: "Deploying Quartz to the Web" |
|---|
| | | tags: |
|---|
| | | - setup |
|---|
| | | weight: -1 |
|---|
| | | aliases: |
|---|
| | | - hosting |
|---|
| | | --- |
|---|
| | | |
|---|
| | | ## 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. |
|---|
| | | |
|---|
| | | ## 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. |
|---|
| | | ### 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. |
|---|
| | | |
|---|
| | | 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. |
|---|
| | | 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. (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 |
|---|
| | | [TODO] |
|---|
| | | 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. |
|---|
| | | |
|---|
| | | ### Custom subdomain |
|---|
| | | Have a fancy custom domain or want to subdomain your Quartz? That's easy too. |
|---|
| | | ```shell |
|---|
| | | # Navigate to Quartz folder |
|---|
| | | cd <path-to-quartz> |
|---|
| | | |
|---|
| | | Change `baseURL` in `/config.toml`. [Reference.](https://github.com/jackyzha0/quartz/blob/hugo/config.toml) |
|---|
| | | # Commit all changes |
|---|
| | | git add . |
|---|
| | | git commit -m "message describing changes" |
|---|
| | | |
|---|
| | | # Push to GitHub to update site |
|---|
| | | 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`. |
|---|
| | | |
|---|
| | | 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>/" |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | Change `cname` in `/.github/workflows/deploy.yaml`. [Reference.](https://github.com/jackyzha0/quartz/blob/hugo/.github/workflows/deploy.yaml) |
|---|
| | | 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!** |
|---|
| | | |
|---|
| | | ```yaml |
|---|
| | | ```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`. |
|---|
| | | |
|---|
| | | Please note that the `cname` field should *not* have any path `e.g. end with /quartz` or have a trailing `/`. |
|---|
| | | |
|---|
| | | [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: |
|---|
| | | 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 |
|---|
| | | 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). |
|---|
| | | Have a custom domain? [Learn how to set it up with Quartz ](notes/custom%20Domain.md). |
|---|
| | | |
|---|
| | | 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 |
|---|
| | | ### Ignoring Files |
|---|
| | | Only want to publish a subset of all of your notes? Don't worry, Quartz makes this a simple two-step process. |
|---|
| | | |
|---|
| | | 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). |
|---|
| | | ❌ [Excluding pages from being published](notes/ignore%20notes.md) |
|---|
| | | |
|---|
| | | *Example Configuration for Quartz* |
|---|
| | | 3. Wait 30 minutes to an hour for the network changes to kick in. |
|---|
| | | 4. Done! |
|---|
| | | ## 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 Quarts](notes/config.md) |
|---|
| | | > Step 6: 🎨 [Customizing Quartz](notes/config.md) |
|---|
| | | |
|---|
| | | Having problems? Checkout our [FAQ and Troubleshooting guide](notes/troubleshooting.md). |
|---|
| | | Having problems? Checkout our [FAQ and Troubleshooting guide](notes/troubleshooting.md). |
|---|
