The Trans Directory
docs: github setup and hosting fixes
+49
-15
+11
-13
docs/hosting.md
+11
-13
docs/hosting.md
···
4
4
5
5
Quartz effectively turns your Markdown files and other resources into a bundle of HTML, JS, and CSS files (a website!).
6
6
7
-
However, if you'd like to publish your site to the world, you need a way to host it online. This guide will detail how to deploy with either GitHub Pages or Cloudflare pages but any service that allows you to deploy static HTML should work as well (e.g. Netlify, Replit, etc.)
7
+
However, if you'd like to publish your site to the world, you need a way to host it online. This guide will detail how to deploy with common hosting providers but any service that allows you to deploy static HTML should work as well.
8
+
9
+
> [!warning]
10
+
> The rest of this guide assumes that you've already created your own GitHub repository for Quartz. If you haven't already, [[setting up your GitHub repository|make sure you do so]].
8
11
9
12
> [!hint]
10
13
> Some Quartz features (like [[RSS Feed]] and sitemap generation) require `baseUrl` to be configured properly in your [[configuration]] to work properly. Make sure you set this before deploying!
···
26
29
27
30
To add a custom domain, check out [Cloudflare's documentation](https://developers.cloudflare.com/pages/platform/custom-domains/).
28
31
29
-
## GitHub Pages
30
-
31
-
Like Quartz 3, you can deploy the site generated by Quartz 4 via GitHub Pages.
32
-
33
32
> [!warning]
34
-
> Quartz generates files in the format of `file.html` instead of `file/index.html` which means the trailing slashes for _non-folder paths_ are dropped. As GitHub pages does not do this redirect, this may cause existing links to your site that use trailing slashes to break. If not breaking existing links is important to you, consider using [[#Cloudflare Pages]].
33
+
> Cloudflare Pages only allows shallow `git` clones so if you rely on `git` for timestamps, it is recommended you either add dates to your frontmatter (see [[authoring content#Syntax]]) or use another hosting provider.
34
+
35
+
## GitHub Pages
35
36
36
37
In your local Quartz, create a new file `quartz/.github/workflows/deploy.yml`.
37
38
···
92
93
> If you get an error about not being allowed to deploy to `github-pages` due to environment protection rules, make sure you remove any existing GitHub pages environments.
93
94
>
94
95
> You can do this by going to your Settings page on your GitHub fork and going to the Environments tab and pressing the trash icon. The GitHub action will recreate the environment for you correctly the next time you sync your Quartz.
96
+
97
+
> [!info]
98
+
> Quartz generates files in the format of `file.html` instead of `file/index.html` which means the trailing slashes for _non-folder paths_ are dropped. As GitHub pages does not do this redirect, this may cause existing links to your site that use trailing slashes to break. If not breaking existing links is important to you (e.g. you are migrating from Quartz 3), consider using [[#Cloudflare Pages]].
95
99
96
100
### Custom Domain
97
101
···
168
172
5. Enter your subdomain into the field and press Add
169
173
170
174
## Netlify
171
-
172
-
Like Vercel, you can also deploy the site generated by Quartz 4 via Netlify.
173
175
174
176
1. Log in to the [Netlify dashboard](https://app.netlify.com/) and click "Add new site".
175
177
2. Select your Git provider and repository containing your Quartz project.
···
180
182
181
183
## GitLab Pages
182
184
183
-
You can configure GitLab CI to build and deploy a Quartz 4 project.
184
-
185
185
In your local Quartz, create a new file `.gitlab-ci.yaml`.
186
186
187
187
```yaml title=".gitlab-ci.yaml"
···
203
203
- hash -r
204
204
- npm ci
205
205
script:
206
-
- npx prettier --write .
207
-
- npm run check
208
206
- npx quartz build
209
207
artifacts:
210
208
paths:
···
227
225
- public
228
226
```
229
227
230
-
When `.gitlab-ci.yaml` is commited, GitLab will build and deploy the website as a GitLab Page. You can find the url under `Deploy` -> `Pages` in the sidebar.
228
+
When `.gitlab-ci.yaml` is commited, GitLab will build and deploy the website as a GitLab Page. You can find the url under `Deploy > Pages` in the sidebar.
231
229
232
230
By default, the page is private and only visible when logged in to a GitLab account with access to the repository but can be opened in the settings under `Deploy` -> `Pages`.
docs/images/github-init-repo-options.png
docs/images/github-init-repo-options.png
This is a binary file and will not be displayed.
docs/images/github-quick-setup.png
docs/images/github-quick-setup.png
This is a binary file and will not be displayed.
+2
-2
docs/index.md
+2
-2
docs/index.md
···
2
2
title: Welcome to Quartz 4
3
3
---
4
4
5
-
Quartz is a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites. Thousands of students, developers, and teachers are [[showcase|already using Quartz]] to publish personal notes, wikis, and [digital gardens](https://jzhao.xyz/posts/networked-thought) to the web.
5
+
Quartz is a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites. Thousands of students, developers, and teachers are [[showcase|already using Quartz]] to publish personal notes, websites, and [digital gardens](https://jzhao.xyz/posts/networked-thought) to the web.
6
6
7
7
## 🪴 Get Started
8
8
···
19
19
20
20
This will guide you through initializing your Quartz with content. Once you've done so, see how to:
21
21
22
-
1. [[authoring content|Author content]] in Quartz
22
+
1. [[authoring content|Writing content]] in Quartz
23
23
2. [[configuration|Configure]] Quartz's behaviour
24
24
3. Change Quartz's [[layout]]
25
25
4. [[build|Build and preview]] Quartz
+31
docs/setting up your GitHub repository.md
+31
docs/setting up your GitHub repository.md
···
1
+
---
2
+
title: Setting up your GitHub repository
3
+
---
4
+
5
+
First, make sure you have Quartz [[index#🪴 Get Started|cloned and setup locally]].
6
+
7
+
Then, create a new repository on GitHub.com. Do **not** initialize the new repository with `README`, license, or `gitignore` files.
8
+
9
+
![[github-init-repo-options.png]]
10
+
11
+
At the top of your repository on GitHub.com's Quick Setup page, click the clipboard to copy the remote repository URL.
12
+
13
+
![[github-quick-setup.png]]
14
+
15
+
In your terminal of choice, navigate to the root of your Quartz folder. Then, run the following command, replacing `REMOTE-URL` with the URL you just copied from the previous step.
16
+
17
+
```bash
18
+
git remote add origin REMOTE-URL
19
+
```
20
+
21
+
To verify that you set the remote URL correctly, run the following command.
22
+
23
+
```bash
24
+
git remote -v
25
+
```
26
+
27
+
Then, you can sync the content to upload it to your repository.
28
+
29
+
```bash
30
+
npx quartz sync
31
+
```
+5
quartz/cli/handlers.js
+5
quartz/cli/handlers.js
···
196
196
)
197
197
await fs.promises.writeFile(configFilePath, configContent)
198
198
199
+
// setup remote
200
+
execSync(
201
+
`git remote show upstream || git remote add upstream https://github.com/jackyzha0/quartz.git`,
202
+
)
203
+
199
204
outro(`You're all set! Not sure what to do next? Try:
200
205
• Customizing Quartz a bit more by editing \`quartz.config.ts\`
201
206
• Running \`npx quartz build --serve\` to preview your Quartz locally