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/components/CategoryList.tsx

@@ -0,0 +1,58 @@
+import { FullSlug, resolveRelative, slugifyFilePath } from "../util/path"
+import { QuartzComponent, QuartzComponentConstructor, QuartzComponentProps } from "./types"
+import { classNames } from "../util/lang"
+
+const CategoryList: QuartzComponent = ({ fileData, displayClass }: QuartzComponentProps) => {
+  const categories = fileData.frontmatter?.categories
+  if (categories && categories.length > 0) {
+    return (
+      <ul class={classNames(displayClass, "categories")}>
+        {categories.map((category) => {
+          // Link directly to the note, not to a category aggregation page
+          const slug = slugifyFilePath((category + ".md") as any)
+          const linkDest = resolveRelative(fileData.slug!, slug)
+          return (
+            <li>
+              <a href={linkDest} class="internal category-link">
+                {category}
+              </a>
+            </li>
+          )
+        })}
+      </ul>
+    )
+  } else {
+    return null
+  }
+}
+
+CategoryList.css = `
+.categories {
+  list-style: none;
+  display: flex;
+  padding-left: 0;
+  gap: 0.4rem;
+  margin: 1rem 0;
+  flex-wrap: wrap;
+}
+
+.section-li > .section > .categories {
+  justify-content: flex-end;
+}
+
+.categories > li {
+  display: inline-block;
+  white-space: nowrap;
+  margin: 0;
+  overflow-wrap: normal;
+}
+
+a.internal.category-link {
+  border-radius: 8px;
+  background-color: var(--highlight);
+  padding: 0.2rem 0.4rem;
+  margin: 0 0.1rem;
+}
+`
+
+export default (() => CategoryList) satisfies QuartzComponentConstructor

quartz/components/index.ts

@@ -1,5 +1,6 @@
 import Content from "./pages/Content"
 import TagContent from "./pages/TagContent"
+import CategoryContent from "./pages/CategoryContent"
 import FolderContent from "./pages/FolderContent"
 import NotFound from "./pages/404"
 import ArticleTitle from "./ArticleTitle"
@@ -12,6 +13,7 @@ import Spacer from "./Spacer"
 import TableOfContents from "./TableOfContents"
 import Explorer from "./Explorer"
 import TagList from "./TagList"
+import CategoryList from "./CategoryList"
 import Graph from "./Graph"
 import Backlinks from "./Backlinks"
 import Search from "./Search"
@@ -28,6 +30,7 @@ export {
   ArticleTitle,
   Content,
   TagContent,
+  CategoryContent,
   FolderContent,
   Darkmode,
   ReaderMode,
@@ -38,6 +41,7 @@ export {
   TableOfContents,
   Explorer,
   TagList,
+  CategoryList,
   Graph,
   Backlinks,
   Search,

quartz/components/pages/CategoryContent.tsx

@@ -0,0 +1,133 @@
+import { QuartzComponent, QuartzComponentConstructor, QuartzComponentProps } from "../types"
+import style from "../styles/listPage.scss"
+import { PageList, SortFn } from "../PageList"
+import { FullSlug, getAllSegmentPrefixes, resolveRelative, simplifySlug } from "../../util/path"
+import { QuartzPluginData } from "../../plugins/vfile"
+import { Root } from "hast"
+import { htmlToJsx } from "../../util/jsx"
+import { i18n } from "../../i18n"
+import { ComponentChildren } from "preact"
+import { concatenateResources } from "../../util/resources"
+
+interface CategoryContentOptions {
+  sort?: SortFn
+  numPages: number
+}
+
+const defaultOptions: CategoryContentOptions = {
+  numPages: 10,
+}
+
+export default ((opts?: Partial<CategoryContentOptions>) => {
+  const options: CategoryContentOptions = { ...defaultOptions, ...opts }
+
+  const CategoryContent: QuartzComponent = (props: QuartzComponentProps) => {
+    const { tree, fileData, allFiles, cfg } = props
+    const slug = fileData.slug
+
+    if (!(slug?.startsWith("categories/") || slug === "categories")) {
+      throw new Error(`Component "CategoryContent" tried to render a non-category page: ${slug}`)
+    }
+
+    const category = simplifySlug(slug.slice("categories/".length) as FullSlug)
+    const allPagesWithCategory = (category: string) =>
+      allFiles.filter((file) =>
+        (file.frontmatter?.categories ?? []).flatMap(getAllSegmentPrefixes).includes(category),
+      )
+
+    const content = (
+      (tree as Root).children.length === 0
+        ? fileData.description
+        : htmlToJsx(fileData.filePath!, tree)
+    ) as ComponentChildren
+    const cssClasses: string[] = fileData.frontmatter?.cssclasses ?? []
+    const classes = cssClasses.join(" ")
+    if (category === "/") {
+      const categories = [
+        ...new Set(
+          allFiles.flatMap((data) => data.frontmatter?.categories ?? []).flatMap(getAllSegmentPrefixes),
+        ),
+      ].sort((a, b) => a.localeCompare(b))
+      const categoryItemMap: Map<string, QuartzPluginData[]> = new Map()
+      for (const category of categories) {
+        categoryItemMap.set(category, allPagesWithCategory(category))
+      }
+      return (
+        <div class="popover-hint">
+          <article class={classes}>
+            <p>{content}</p>
+          </article>
+          <p>{i18n(cfg.locale).pages.categoryContent.totalCategories({ count: categories.length })}</p>
+          <div>
+            {categories.map((category) => {
+              const pages = categoryItemMap.get(category)!
+              const listProps = {
+                ...props,
+                allFiles: pages,
+              }
+
+              const contentPage = allFiles.filter((file) => file.slug === `categories/${category}`).at(0)
+
+              const root = contentPage?.htmlAst
+              const content =
+                !root || root?.children.length === 0
+                  ? contentPage?.description
+                  : htmlToJsx(contentPage.filePath!, root)
+
+              const categoryListingPage = `/categories/${category}` as FullSlug
+              const href = resolveRelative(fileData.slug!, categoryListingPage)
+
+              return (
+                <div>
+                  <h2>
+                    <a class="internal category-link" href={href}>
+                      {category}
+                    </a>
+                  </h2>
+                  {content && <p>{content}</p>}
+                  <div class="page-listing">
+                    <p>
+                      {i18n(cfg.locale).pages.categoryContent.itemsUnderCategory({ count: pages.length })}
+                      {pages.length > options.numPages && (
+                        <>
+                          {" "}
+                          <span>
+                            {i18n(cfg.locale).pages.categoryContent.showingFirst({
+                              count: options.numPages,
+                            })}
+                          </span>
+                        </>
+                      )}
+                    </p>
+                    <PageList limit={options.numPages} {...listProps} sort={options?.sort} />
+                  </div>
+                </div>
+              )
+            })}
+          </div>
+        </div>
+      )
+    } else {
+      const pages = allPagesWithCategory(category)
+      const listProps = {
+        ...props,
+        allFiles: pages,
+      }
+
+      return (
+        <div class="popover-hint">
+          <article class={classes}>{content}</article>
+          <div class="page-listing">
+            <p>{i18n(cfg.locale).pages.categoryContent.itemsUnderCategory({ count: pages.length })}</p>
+            <div>
+              <PageList {...listProps} sort={options?.sort} />
+            </div>
+          </div>
+        </div>
+      )
+    }
+  }
+
+  CategoryContent.css = concatenateResources(style, PageList.css)
+  return CategoryContent
+}) satisfies QuartzComponentConstructor

quartz/i18n/locales/definition.ts

@@ -84,5 +84,12 @@ export interface Translation {
       showingFirst: (variables: { count: number }) => string
       totalTags: (variables: { count: number }) => string
     }
+    categoryContent: {
+      category: string
+      categoryIndex: string
+      itemsUnderCategory: (variables: { count: number }) => string
+      showingFirst: (variables: { count: number }) => string
+      totalCategories: (variables: { count: number }) => string
+    }
   }
 }

quartz/i18n/locales/en-US.ts

@@ -83,5 +83,13 @@ export default {
       showingFirst: ({ count }) => `Showing first ${count} tags.`,
       totalTags: ({ count }) => `Found ${count} total tags.`,
     },
+    categoryContent: {
+      category: "Category",
+      categoryIndex: "Category Index",
+      itemsUnderCategory: ({ count }) =>
+        count === 1 ? "1 item in this category." : `${count} items in this category.`,
+      showingFirst: ({ count }) => `Showing first ${count} categories.`,
+      totalCategories: ({ count }) => `Found ${count} total categories.`,
+    },
   },
 } as const satisfies Translation

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]
           }
         },
       ]