🦾 Quartz

Executive Summary

Quartz is the engine powering our documentation wiki (/dev/docs/wiki). It compiles Obsidian Flavored Markdown (OFM) into a static site. This skill outlines the operating procedures for modifying Quartz configuration, updating the content taxonomy, managing routes, and ensuring the wiki remains robust and fully functional within the Funday developer ecosystem.

When to use / When NOT to use

Use When:

• Modifying wiki layout, themes, or components.
• Restructuring the documentation hierarchy (moving folders/files).
• Creating custom components or extending Quartz capabilities.
• Updating quartz.config.yaml or quartz.layout.ts.

When NOT to use:

• Just writing standard documentation (that’s general Markdown work).
• Modifying the SvelteKit shell around the wiki (handled in the frontend app).
• Trying to fix styling inside the public/ directory (these are generated build artifacts).

Rules

1. Source Truth, Not Build Output

NEVER edit files in the public/ folder. These are build outputs and will be overwritten on the next compile. Always edit the source Markdown in content/ or the TypeScript/SCSS source in the quartz/ directory.

2. Preserve URL Integrity (Aliases)

When moving or renaming a Markdown file, you MUST add the old route to the frontmatter aliases array. Quartz uses these aliases to generate HTTP redirects or duplicate files, ensuring inbound links from Slack, GitHub, or older docs do not 404.

• Aliases are always content-relative, meaning they do not include the /dev/docs/ or /dev/docs/wiki/ prefix.

3. Extend, Don’t Mutate

When adding functionality, prefer creating local custom components in quartz/components/ over forking or deeply mutating upstream Quartz plugins, to maintain an easier upgrade path.

4. Build and Verify

After changing content or configuration, rebuild the docs locally. Do not assume your frontmatter changes or link updates are valid without a successful build.

• cd /home/usr/funday/dev/docs && npm run build:docs

Examples

Moving a File Safely

Before (at content/guides/Deployment.md):

---
title: Deployment Guide
---

After (moved to content/ops/Deploying.md):

---
title: Deploying the Platform
aliases:
  - guides/Deployment
---

Rebuilding the Wiki

cd /home/usr/funday/dev/docs
npm run build:docs

Failure Modes / Checks

1. Broken Links: Quartz emits warnings during build if internal links ([[Some Page]] or [Link](./Some-Page)) do not resolve. Check the build output.
2. Missing Aliases: Moving a highly-trafficked page without setting an alias results in silent 404s for users with bookmarks.
3. YAML Syntax Errors: Unquoted colons or bad indentation in frontmatter will break the page parser, often resulting in a blank page or a build crash.
4. Shell/Iframe Desync: Ensure you are editing the Quartz styles (quartz/styles/custom.scss), not the SvelteKit wrapper styles, when adjusting wiki-specific elements.

Related Links

• Quartz Official Documentation
• Skill MD Guru