LLM Best Practices

Quartz Config: quartz.config.ts

Last updated 3 min read

View markdown source

AI agents: read this first: llmbestpractices.com/start-here

This is LLM Best Practices (llmbestpractices.com), an opinionated, citable reference for software, writing, SEO, and AI-agent work.

  1. Route, do not crawl. Fetch llmbestpractices.com/llms.txt and open only the pages whose one-line summary matches your task.
  2. Read raw. Append .md to any page URL for markdown. Check status and last_updated in the frontmatter, then read the rules.
  3. Apply as defaults. First-party docs and the project's own conventions win on conflict. Warn before relying on a fast-moving page older than 12 months.
  4. Cite. Link the page by title and URL, e.g. Python, with last_updated for time-sensitive rules. License CC BY 4.0.

Overview

quartz.config.ts exports one QuartzConfig object with two keys: configuration (site settings) and plugins (the three plugin arrays, covered in quartz-plugins). Everything below was checked against Quartz 4.5.2 source.

Set baseUrl to the bare domain

baseUrl feeds the sitemap, the RSS feed, canonical URLs in this site’s head component, and the CNAME emitter. Write the host only: no https://, no trailing slash.

baseUrl: "llmbestpractices.com",

The CNAME emitter writes only the hostname parsed from baseUrl to public/CNAME. Add Plugin.CNAME() for a custom domain, and not for a user.github.io/repo project URL, where the hostname would be wrong. See quartz-deployment.

Anchor ignorePatterns at the content root

ignorePatterns: ["private", "templates", ".obsidian"],

Patterns are globs relative to content/, and an entry like private matches only the top-level folder. A nested notes/private/ is still published; write **/private to catch it. The glob call also honors .gitignore files inside content/. A missing pattern ships drafts, so add patterns before the first deploy.

Know which frontmatter keys set dates

defaultDateType is "created", "modified", or "published" and picks which date the page shows. CreatedModifiedDate fills each date from priority, default ["frontmatter", "git", "filesystem"].

  • Frontmatter keys read: created or date; modified, lastmod, updated, or last-modified; published or publishDate.
  • This site’s last_updated is not a Quartz key, so it never sets the displayed date. The date comes from the file’s last git commit.
  • Git supplies only the modified date, and needs full history in CI (fetch-depth: 0).
  • An unparseable date logs a warning and falls back to the build time.

To control the displayed date, add modified: 2026-10-01 alongside last_updated.

Pick a font mode in theme

theme: {
  fontOrigin: "googleFonts",
  cdnCaching: false,
  typography: { header: "Schibsted Grotesk", body: "Source Sans Pro", code: "IBM Plex Mono" },
  colors: { lightMode: { /* 9 keys */ }, darkMode: { /* 9 keys */ } },
}
  • fontOrigin: "googleFonts" with cdnCaching: true: pages link to Google Fonts at runtime.
  • "googleFonts" with cdnCaching: false: the build fetches the CSS and font files and serves them from /static/fonts/, so visitors make no Google request. The build then needs network access. This site uses this mode.
  • fontOrigin: "local": Quartz emits no font CSS; you write the @font-face rules yourself.

Each color scheme has nine keys: light, lightgray, gray, darkgray, dark, secondary, tertiary, highlight, textHighlight. They become CSS custom properties such as var(--secondary). scripts/check-identity.mjs fails when content/identity.md drifts from the fonts and palette here.

Use pageTitle for the site name and the suffix for <title>

pageTitle is the site name shown by the PageTitle component. The browser <title> is the page’s own title plus pageTitleSuffix.

pageTitle: "LLM Best Practices",
pageTitleSuffix: " · llmbestpractices",

Set the remaining switches deliberately

  • enableSPA and enablePopovers are required fields; the stock template sets both to true for single-page navigation and hover previews.
  • analytics takes one provider object or null. This site keeps it null; add none without an explicit decision.
  • locale: "en-US" drives date formatting and built-in UI text.

Type-check the config

The file imports QuartzConfig from ./quartz/cfg, so a missing required field fails npx tsc --noEmit. Run it before committing config changes.

Backlinks