feat: implement breadcrumb component (#508)

* feat: implement breadcrumbs

* style: fix styling, move breadcrumbs to top

* refactor: move `capitalize to `lang.ts``

* refactor: clean breadcrumb generation

* feat: add options to breadcrumbs

* feat: implement `resolveFrontmatterTitle`

* feat: add `hideOnRoot` option

* feat(consistency): capitalize every crumb

* style: add `flex-wrap` to parent container

* refactor: clean `Breadcrumbs.tsx`

* feat(accessibility): use `nav`, add aria label

* style: improve look in popovers by adding margin

* docs: write docs for breadcrumb component

* refactor: collapse `if` condition for hideOnRoot

* chore: add todo for perf optimization

* docs: update introduction

quartz/components/Breadcrumbs.tsx

@@ -0,0 +1,118 @@
+import { QuartzComponentConstructor, QuartzComponentProps } from "./types"
+import breadcrumbsStyle from "./styles/breadcrumbs.scss"
+import { FullSlug, SimpleSlug, resolveRelative } from "../util/path"
+import { capitalize } from "../util/lang"
+import { QuartzPluginData } from "../plugins/vfile"
+
+type CrumbData = {
+  displayName: string
+  path: string
+}
+
+interface BreadcrumbOptions {
+  /**
+   * Symbol between crumbs
+   */
+  spacerSymbol: string
+  /**
+   * Name of first crumb
+   */
+  rootName: string
+  /**
+   * wether to look up frontmatter title for folders (could cause performance problems with big vaults)
+   */
+  resolveFrontmatterTitle: boolean
+  /**
+   * Wether to display breadcrumbs on root `index.md`
+   */
+  hideOnRoot: boolean
+}
+
+const defaultOptions: BreadcrumbOptions = {
+  spacerSymbol: ">",
+  rootName: "Home",
+  resolveFrontmatterTitle: false,
+  hideOnRoot: true,
+}
+
+function formatCrumb(displayName: string, baseSlug: FullSlug, currentSlug: SimpleSlug): CrumbData {
+  return { displayName, path: resolveRelative(baseSlug, currentSlug) }
+}
+
+// given a folderName (e.g. "features"), search for the corresponding `index.md` file
+function findCurrentFile(allFiles: QuartzPluginData[], folderName: string) {
+  return allFiles.find((file) => {
+    if (file.slug?.endsWith("index")) {
+      const folderParts = file.filePath?.split("/")
+      if (folderParts) {
+        const name = folderParts[folderParts?.length - 2]
+        if (name === folderName) {
+          return true
+        }
+      }
+    }
+  })
+}
+
+export default ((opts?: Partial<BreadcrumbOptions>) => {
+  // Merge options with defaults
+  const options: BreadcrumbOptions = { ...defaultOptions, ...opts }
+
+  function Breadcrumbs({ fileData, allFiles }: QuartzComponentProps) {
+    // Hide crumbs on root if enabled
+    if (options.hideOnRoot && fileData.slug === "index") {
+      return <></>
+    }
+
+    // Format entry for root element
+    const firstEntry = formatCrumb(capitalize(options.rootName), fileData.slug!, "/" as SimpleSlug)
+    const crumbs: CrumbData[] = [firstEntry]
+
+    // Get parts of filePath (every folder)
+    const parts = fileData.filePath?.split("/")?.splice(1)
+    if (parts) {
+      // full path until current part
+      let current = ""
+      for (let i = 0; i < parts.length - 1; i++) {
+        const folderName = parts[i]
+        let currentTitle = folderName
+
+        // TODO: performance optimizations/memoizing
+        // Try to resolve frontmatter folder title
+        if (options?.resolveFrontmatterTitle) {
+          // try to find file for current path
+          const currentFile = findCurrentFile(allFiles, folderName)
+          if (currentFile) {
+            currentTitle = currentFile.frontmatter!.title
+          }
+        }
+        // Add current path to full path
+        current += folderName + "/"
+
+        // Format and add current crumb
+        const crumb = formatCrumb(capitalize(currentTitle), fileData.slug!, current as SimpleSlug)
+        crumbs.push(crumb)
+      }
+
+      // Add current file to crumb (can directly use frontmatter title)
+      if (parts.length > 0) {
+        crumbs.push({
+          displayName: capitalize(fileData.frontmatter!.title),
+          path: "",
+        })
+      }
+    }
+    return (
+      <nav class="breadcrumb-container" aria-label="breadcrumbs">
+        {crumbs.map((crumb, index) => (
+          <div class="breadcrumb-element">
+            <a href={crumb.path}>{crumb.displayName}</a>
+            {index !== crumbs.length - 1 && <p>{` ${options.spacerSymbol} `}</p>}
+          </div>
+        ))}
+      </nav>
+    )
+  }
+  Breadcrumbs.css = breadcrumbsStyle
+  return Breadcrumbs
+}) satisfies QuartzComponentConstructor

quartz/components/index.ts

@@ -18,6 +18,7 @@ import Footer from "./Footer"
 import DesktopOnly from "./DesktopOnly"
 import MobileOnly from "./MobileOnly"
 import RecentNotes from "./RecentNotes"
+import Breadcrumbs from "./Breadcrumbs"
 
 export {
   ArticleTitle,
@@ -40,4 +41,5 @@ export {
   MobileOnly,
   RecentNotes,
   NotFound,
+  Breadcrumbs,
 }

quartz/components/styles/breadcrumbs.scss

@@ -0,0 +1,22 @@
+.breadcrumb-container {
+  margin: 0;
+  margin-top: 0.75rem;
+  padding: 0;
+  display: flex;
+  flex-direction: row;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+}
+
+.breadcrumb-element {
+  p {
+    margin: 0;
+    margin-left: 0.5rem;
+    padding: 0;
+    line-height: normal;
+  }
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  justify-content: center;
+}