Building your quartz

raw/Home Office/Building your Quartz.md

@@ -0,0 +1,121 @@
+---
+title: Building your Quartz
+source: https://quartz.jzhao.xyz/build
+author:
+published: 2026-03-04
+created: 2026-04-17
+description: "Once you’ve initialized Quartz, let’s see what it looks like locally: npx quartz build --serve This will start a local web server to run your Quartz on your computer."
+tags:
+  - clippings
+  - quartz
+  - obsidian
+---
+Once you’ve [initialized](https://quartz.jzhao.xyz/#-get-started) Quartz, let’s see what it looks like locally:
+
+```bash
+npx quartz build --directory /Users/weishen/Workspace/nexus/wiki --output /Users/weishen/Workspace/quartz --serve
+```
+
+This will start a local web server to run your Quartz on your computer. Open a web browser and visit `http://localhost:8080/` to view it.
+
+> Flags and options
+> 
+> For full help options, you can run `npx quartz build --help`.
+> 
+> Most of these have sensible defaults but you can override them if you have a custom setup:
+> 
+> - `-d` or `--directory`: the content folder. This is normally just `content`
+> - `-v` or `--verbose`: print out extra logging information
+> - `-o` or `--output`: the output folder. This is normally just `public`
+> - `--serve`: run a local hot-reloading server to preview your Quartz
+> - `--port`: what port to run the local preview server on
+> - `--concurrency`: how many threads to use to parse notes
+
+> Not to be used for production
+> 
+> Serve mode is intended for local previews only. For production workloads, see the page on [hosting](https://quartz.jzhao.xyz/hosting).
+
+---
+
+Building your Quartz
+
+Quartz effectively turns your Markdown files and other resources into a bundle of HTML, JS, and CSS files (a website!).
+
+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.
+
+> Warning
+> 
+> The rest of this guide assumes that you’ve already created your own GitHub repository for Quartz. If you haven’t already, [make sure you do so](https://quartz.jzhao.xyz/setting-up-your-GitHub-repository).
+
+> Hint
+> 
+> Some Quartz features (like [RSS Feed](https://quartz.jzhao.xyz/features/RSS-Feed) and sitemap generation) require `baseUrl` to be configured properly in your [configuration](https://quartz.jzhao.xyz/configuration) to work properly. Make sure you set this before deploying!
+
+
+## Self-Hosting
+
+Copy the `public` directory to your web server and configure it to serve the files. You can use any web server to host your site. Since Quartz generates links that do not include the `.html` extension, you need to let your web server know how to deal with it.
+
+### Using Nginx
+
+Here’s an example of how to do this with Nginx:
+
+nginx.conf
+
+```nginx
+server {
+    listen 80;
+    server_name example.com;
+    root /path/to/quartz/public;
+    index index.html;
+    error_page 404 /404.html;
+ 
+    location / {
+        try_files $uri $uri.html $uri/ =404;
+    }
+}
+```
+
+### Using Apache
+
+Here’s an example of how to do this with Apache:
+
+.htaccess
+
+```apache
+RewriteEngine On
+ 
+ErrorDocument 404 /404.html
+ 
+# Rewrite rule for .html extension removal (with directory check)
+RewriteCond %{REQUEST_FILENAME} !-f
+RewriteCond %{REQUEST_FILENAME} !-d
+RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_URI}.html -f
+RewriteRule ^(.*)$ $1.html [L]
+ 
+# Handle directory requests explicitly
+RewriteCond %{REQUEST_FILENAME} -d
+RewriteRule ^(.*)/$ $1/index.html [L]
+```
+
+Don’t forget to activate brotli / gzip compression.
+
+### Using Caddy
+
+Here’s and example of how to do this with Caddy:
+
+Caddyfile
+
+```caddy
+example.com {
+    root * /path/to/quartz/public
+    try_files {path} {path}.html {path}/ =404
+    file_server
+    encode gzip
+ 
+    handle_errors {
+        rewrite * /{err.status_code}.html
+        file_server
+    }
+}
+```