Concise rules and checklist for keeping the Developer Docs useful, source-backed, and well-configured under Quartz.

1. 📊 Sources

funday/funday-codex.yml is the machine SSOT. funday/funday-bible.md is the human companion. Current repo files beat memory or stale generated output.

2. 🌑 Visuals

The wiki is dark-first. Dates render as YYYY-MM-DD hh:mm; content pages do not show read time. Mobile chrome and layout must not use global width: 100vw or overlapping fixed elements.

3. 💬 Comments

Remark42 is the default private-server comments provider on FUNDOCS (/dev/docs/wiki/). Full integration SSOT: FUNDOCS Comments.

3b. 📖 FUNDOCS shell

Developer docs use a Hermes-style split: SvelteKit shell at /dev/docs, Quartz wiki iframe at /dev/docs/wiki/. See FUNDOCS Architecture.

4. 🧱 Output

Never hand-edit generated public/ output. Make durable edits in source content or quartz-custom/.

5. 🔐 Secrets

Cite source paths and keys, not secret values. Server-only config stays server-only.

6. 🧭 Headings

Use concise titles and headings. Put extra context in the paragraph below. Prefer phases, steps, and substeps over time estimates.

7. 🗺️ Diagrams

Mermaid labels with emoji or punctuation are quoted, diagrams stay sparse.

---

✅ Quartz Configuration Checklist

📋 Quartz 5 Best Practices Task Flow

To maintain a clean, organized, and high-performance Quartz 5 documentation tree, follow this structured task flow:

1. 🏷️ Title Optimization: Use exact frontmatter title.
2. 🏗️ Root Navigation: One hierarchy.

📚 Developer Docs

Quartz source files live under funday/dev/docs/content; generated public/ output is never hand-edited.

Steps

1. Edit source content or local Quartz customizations only.

2. For production publication, run npm run build:docs from inside the docs folder. This performs an atomic release with staging, validation, and pointer swap.

3. For local, non-publishing validation of changes before publication, build to a temporary directory and remove it afterward:

   cd /home/usr/funday/dev/docs
   npx quartz build --output /tmp/quartz-validate-$$
   rm -rf /tmp/quartz-validate-*

   Do not run npx quartz build directly into public/ on the production host; the live wiki is served from the atomic release directory managed by npm run build:docs.