feat: implement wiki-linked categories with graph and backlinks integration

Add complete category system that integrates with Obsidian's wiki-linked
category frontmatter. Categories appear as pills on pages and link directly
to category notes (not aggregation pages).

Features:
- Parse [[Page Name]] syntax from category frontmatter
- Display category pills styled like tags
- Link directly to category notes
- Integrate with graph view connections
- Enable bidirectional backlinks
- Preserve case in category slugs

Implementation:
- Added extractWikiLinks() to frontmatter transformer
- Created CategoryList component for pill rendering
- Modified links transformer to include categories in links array
- Updated contentIndex to export category metadata
- Added i18n strings for category UI elements
- Set includeEmptyFiles: true to show empty category pages in graph

Files modified:
- quartz/plugins/transformers/frontmatter.ts
- quartz/plugins/transformers/links.ts
- quartz/plugins/emitters/contentIndex.tsx
- quartz/components/CategoryList.tsx (new)
- quartz/components/pages/CategoryContent.tsx (new)
- quartz/plugins/emitters/categoryPage.tsx (new)
- quartz/i18n/locales/en-US.ts
- quartz/i18n/locales/definition.ts
- quartz/components/index.ts
- quartz.layout.ts
- quartz.config.ts
- README.md (updated with Quartz updater documentation)

Security: Comprehensive privacy review confirms NO information leaks from
private folder. All ignore patterns working correctly.

Docs: Added CUSTOMIZATIONS.md with complete feature documentation,
implementation details, and privacy audit results.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

quartz/plugins/emitters/categoryPage.tsx

@@ -0,0 +1,170 @@
+import { QuartzEmitterPlugin } from "../types"
+import { QuartzComponentProps } from "../../components/types"
+import HeaderConstructor from "../../components/Header"
+import BodyConstructor from "../../components/Body"
+import { pageResources, renderPage } from "../../components/renderPage"
+import { ProcessedContent, QuartzPluginData, defaultProcessedContent } from "../vfile"
+import { FullPageLayout } from "../../cfg"
+import { FullSlug, getAllSegmentPrefixes, joinSegments, pathToRoot } from "../../util/path"
+import { defaultListPageLayout, sharedPageComponents } from "../../../quartz.layout"
+import { CategoryContent } from "../../components"
+import { write } from "./helpers"
+import { i18n, TRANSLATIONS } from "../../i18n"
+import { BuildCtx } from "../../util/ctx"
+import { StaticResources } from "../../util/resources"
+
+interface CategoryPageOptions extends FullPageLayout {
+  sort?: (f1: QuartzPluginData, f2: QuartzPluginData) => number
+}
+
+function computeCategoryInfo(
+  allFiles: QuartzPluginData[],
+  content: ProcessedContent[],
+  locale: keyof typeof TRANSLATIONS,
+): [Set<string>, Record<string, ProcessedContent>] {
+  const categories: Set<string> = new Set(
+    allFiles.flatMap((data) => data.frontmatter?.categories ?? []).flatMap(getAllSegmentPrefixes),
+  )
+
+  // add base category
+  categories.add("index")
+
+  const categoryDescriptions: Record<string, ProcessedContent> = Object.fromEntries(
+    [...categories].map((category) => {
+      const title =
+        category === "index"
+          ? i18n(locale).pages.categoryContent.categoryIndex
+          : `${i18n(locale).pages.categoryContent.category}: ${category}`
+      return [
+        category,
+        defaultProcessedContent({
+          slug: joinSegments("categories", category) as FullSlug,
+          frontmatter: { title, categories: [] },
+        }),
+      ]
+    }),
+  )
+
+  // Update with actual content if available
+  for (const [tree, file] of content) {
+    const slug = file.data.slug!
+    if (slug.startsWith("categories/")) {
+      const category = slug.slice("categories/".length)
+      if (categories.has(category)) {
+        categoryDescriptions[category] = [tree, file]
+        if (file.data.frontmatter?.title === category) {
+          file.data.frontmatter.title = `${i18n(locale).pages.categoryContent.category}: ${category}`
+        }
+      }
+    }
+  }
+
+  return [categories, categoryDescriptions]
+}
+
+async function processCategoryPage(
+  ctx: BuildCtx,
+  category: string,
+  categoryContent: ProcessedContent,
+  allFiles: QuartzPluginData[],
+  opts: FullPageLayout,
+  resources: StaticResources,
+) {
+  const slug = joinSegments("categories", category) as FullSlug
+  const [tree, file] = categoryContent
+  const cfg = ctx.cfg.configuration
+  const externalResources = pageResources(pathToRoot(slug), resources)
+  const componentData: QuartzComponentProps = {
+    ctx,
+    fileData: file.data,
+    externalResources,
+    cfg,
+    children: [],
+    tree,
+    allFiles,
+  }
+
+  const content = renderPage(cfg, slug, componentData, opts, externalResources)
+  return write({
+    ctx,
+    content,
+    slug: file.data.slug!,
+    ext: ".html",
+  })
+}
+
+export const CategoryPage: QuartzEmitterPlugin<Partial<CategoryPageOptions>> = (userOpts) => {
+  const opts: FullPageLayout = {
+    ...sharedPageComponents,
+    ...defaultListPageLayout,
+    pageBody: CategoryContent({ sort: userOpts?.sort }),
+    ...userOpts,
+  }
+
+  const { head: Head, header, beforeBody, pageBody, afterBody, left, right, footer: Footer } = opts
+  const Header = HeaderConstructor()
+  const Body = BodyConstructor()
+
+  return {
+    name: "CategoryPage",
+    getQuartzComponents() {
+      return [
+        Head,
+        Header,
+        Body,
+        ...header,
+        ...beforeBody,
+        pageBody,
+        ...afterBody,
+        ...left,
+        ...right,
+        Footer,
+      ]
+    },
+    async *emit(ctx, content, resources) {
+      const allFiles = content.map((c) => c[1].data)
+      const cfg = ctx.cfg.configuration
+      const [categories, categoryDescriptions] = computeCategoryInfo(allFiles, content, cfg.locale)
+
+      for (const category of categories) {
+        yield processCategoryPage(ctx, category, categoryDescriptions[category], allFiles, opts, resources)
+      }
+    },
+    async *partialEmit(ctx, content, resources, changeEvents) {
+      const allFiles = content.map((c) => c[1].data)
+      const cfg = ctx.cfg.configuration
+
+      // Find all categories that need to be updated based on changed files
+      const affectedCategories: Set<string> = new Set()
+      for (const changeEvent of changeEvents) {
+        if (!changeEvent.file) continue
+        const slug = changeEvent.file.data.slug!
+
+        // If it's a category page itself that changed
+        if (slug.startsWith("categories/")) {
+          const category = slug.slice("categories/".length)
+          affectedCategories.add(category)
+        }
+
+        // If a file with categories changed, we need to update those category pages
+        const fileCategories = changeEvent.file.data.frontmatter?.categories ?? []
+        fileCategories.flatMap(getAllSegmentPrefixes).forEach((category) => affectedCategories.add(category))
+
+        // Always update the index category page if any file changes
+        affectedCategories.add("index")
+      }
+
+      // If there are affected categories, rebuild their pages
+      if (affectedCategories.size > 0) {
+        // We still need to compute all categories because category pages show all categories
+        const [_categories, categoryDescriptions] = computeCategoryInfo(allFiles, content, cfg.locale)
+
+        for (const category of affectedCategories) {
+          if (categoryDescriptions[category]) {
+            yield processCategoryPage(ctx, category, categoryDescriptions[category], allFiles, opts, resources)
+          }
+        }
+      }
+    },
+  }
+}

quartz/plugins/emitters/contentIndex.tsx

@@ -19,6 +19,10 @@ export type ContentDetails = {
   richContent?: string
   date?: Date
   description?: string
+  frontmatter?: {
+    categories?: string[]
+    [key: string]: any
+  }
 }
 
 interface Options {
@@ -115,6 +119,9 @@ export const ContentIndex: QuartzEmitterPlugin<Partial<Options>> = (opts) => {
               : undefined,
             date: date,
             description: file.data.description ?? "",
+            frontmatter: {
+              categories: file.data.frontmatter?.categories ?? [],
+            },
           })
         }
       }

quartz/plugins/emitters/index.ts

@@ -1,5 +1,6 @@
 export { ContentPage } from "./contentPage"
 export { TagPage } from "./tagPage"
+export { CategoryPage } from "./categoryPage"
 export { FolderPage } from "./folderPage"
 export { ContentIndex as ContentIndex } from "./contentIndex"
 export { AliasRedirects } from "./aliases"

quartz/plugins/transformers/frontmatter.ts

@@ -3,7 +3,7 @@ import remarkFrontmatter from "remark-frontmatter"
 import { QuartzTransformerPlugin } from "../types"
 import yaml from "js-yaml"
 import toml from "toml"
-import { FilePath, FullSlug, getFileExtension, slugifyFilePath, slugTag } from "../../util/path"
+import { FilePath, FullSlug, getFileExtension, simplifySlug, slugifyFilePath, slugTag } from "../../util/path"
 import { QuartzPluginData } from "../vfile"
 import { i18n } from "../../i18n"
 
@@ -40,6 +40,14 @@ function coerceToArray(input: string | string[]): string[] | undefined {
     .map((tag: string | number) => tag.toString())
 }
 
+function extractWikiLinks(input: string[]): string[] {
+  // Extract page names from wiki links like [[Page Name]] -> Page Name
+  return input.map((item) => {
+    const wikiLinkMatch = item.match(/^\[\[(.+?)\]\]$/)
+    return wikiLinkMatch ? wikiLinkMatch[1] : item
+  })
+}
+
 function getAliasSlugs(aliases: string[]): FullSlug[] {
   const res: FullSlug[] = []
   for (const alias of aliases) {
@@ -80,6 +88,17 @@ export const FrontMatter: QuartzTransformerPlugin<Partial<Options>> = (userOpts)
             const tags = coerceToArray(coalesceAliases(data, ["tags", "tag"]))
             if (tags) data.tags = [...new Set(tags.map((tag: string) => slugTag(tag)))]
 
+            const categories = coerceToArray(coalesceAliases(data, ["categories", "category"]))
+            if (categories) {
+              // Extract page names from wiki links and slugify them like regular page links
+              const categoryNames = extractWikiLinks(categories)
+              data.categories = [...new Set(categoryNames.map((cat: string) => {
+                // Use slugifyFilePath to match how pages are slugified
+                const slug = slugifyFilePath((cat + ".md") as any)
+                return simplifySlug(slug)
+              }))]
+            }
+
             const aliases = coerceToArray(coalesceAliases(data, ["aliases", "alias"]))
             if (aliases) {
               data.aliases = aliases // frontmatter
@@ -139,6 +158,7 @@ declare module "vfile" {
       title: string
     } & Partial<{
         tags: string[]
+        categories: string[]
         aliases: string[]
         modified: string
         created: string

quartz/plugins/transformers/links.ts

@@ -159,7 +159,9 @@ export const CrawlLinks: QuartzTransformerPlugin<Partial<Options>> = (userOpts)
               }
             })
 
-            file.data.links = [...outgoing]
+            // Include categories as links for backlinks and graph
+            const categories = file.data.frontmatter?.categories ?? []
+            file.data.links = [...outgoing, ...categories]
           }
         },
       ]