Quartz's default explorer plugin.
  • TypeScript 84.5%
  • SCSS 15.5%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-10 20:53:12 +01:00
.changeset chore: version package 2026-11-10 19:43:40 +00:00
.github/workflows ci: run ci.yml on the changesets version PR and report it as a commit status 2026-11-09 03:47:26 +01:00
src fix: in a one-screen sidebar the explorer shrinks and scrolls before recent notes and other components below it 2026-11-10 20:30:17 +01:00
test fix: resolve ESLint and formatting issues for CI compliance 2026-03-09 03:47:39 +01:00
types fix: use fetchData global for path-prefixed deployments 2026-03-16 18:54:25 +01:00
.eslintrc.json fix: use fetchData global for path-prefixed deployments 2026-03-16 18:54:25 +01:00
.gitignore chore: migrate to npm publishing 2026-07-23 09:07:06 +02:00
.prettierignore fix: use fetchData global for path-prefixed deployments 2026-03-16 18:54:25 +01:00
.prettierrc Initial commit 2026-02-07 02:03:54 +01:00
CHANGELOG.md chore: version package 2026-11-10 19:43:40 +00:00
LICENSE Initial commit 2026-02-07 02:03:54 +01:00
package-lock.json chore: version package 2026-11-10 19:43:40 +00:00
package.json chore: version package 2026-11-10 19:43:40 +00:00
README.md docs(readme): Quartz 5.1 — npm install and config, correct options and defaults 2026-11-09 22:57:48 +01:00
tsconfig.build.json fix: use separate tsconfig for DTS build to avoid vitest dependency 2026-03-22 13:12:01 +01:00
tsconfig.json fix: use fetchData global for path-prefixed deployments 2026-03-16 18:54:25 +01:00
tsup.config.ts build: keep preact and the other shared packages external (tsup's noExternal overrode them) 2026-11-09 04:49:21 +01:00
vitest.config.ts fix: explorer not loading 2026-02-09 20:24:35 +01:00

@quartz-community/explorer

The Explorer component for Quartz - navigate your digital garden with an interactive file tree.

Features

  • 📁 Interactive folder tree with collapse/expand functionality
  • 📱 Mobile-friendly slide-out navigation
  • 💾 Persistent state (remembers open/closed folders)
  • 🔗 Configurable folder click behavior (link or collapse)
  • ⚡ Built-in search and overflow handling

Installation

npx quartz plugin add @quartz-community/explorer

Usage

This plugin is already enabled in the default quartz.config.yaml:

plugins:
  - source: "@quartz-community/explorer"
    enabled: true
    options:
      folderClickBehavior: link
      folderDefaultState: collapsed
      useSavedState: true
    layout:
      position: left
      priority: 50

Callback options (sortFn, filterFn, mapFn) can't be expressed in YAML. Set them in a TypeScript override:

import * as ExternalPlugin from "./.quartz/plugins";

// Must be placed before loadQuartzConfig()
ExternalPlugin.Explorer({
  mapFn: (node) => {
    node.displayName = node.displayName.toUpperCase();
    return node;
  },
});

Configuration Options

interface ExplorerOptions {
  /** Title displayed above the explorer (default: the localized "Explorer") */
  title?: string;

  /** Default state for folders: "collapsed" or "open" (default: "collapsed") */
  folderDefaultState: "collapsed" | "open";

  /** Behavior when clicking folders: "collapse" to toggle, "link" to navigate (default: "link") */
  folderClickBehavior: "collapse" | "link";

  /** Whether to persist folder state in localStorage (default: true) */
  useSavedState: boolean;

  /** Custom sort function for entries */
  sortFn?: (a: FileTrieNode, b: FileTrieNode) => number;

  /** Custom filter function for entries */
  filterFn?: (node: FileTrieNode) => boolean;

  /** Custom map function for transforming entries; returns the (modified) node */
  mapFn?: (node: FileTrieNode) => FileTrieNode;

  /** Order in which to apply filter, map, and sort (default: ["filter", "map", "sort"]) */
  order?: Array<"filter" | "map" | "sort">;
}

Default Behavior

By default, the Explorer:

  • Shows folders in a collapsed state
  • Opens folders when clicked (navigates to index page)
  • Saves folder states between sessions
  • Excludes the "tags" folder from the tree
  • Sorts folders first, then files alphabetically (with numeric ordering)

Development

This is a first-party Quartz community plugin. It serves as both:

  1. A production-ready Explorer component
  2. A reference implementation for building Quartz community plugins

Documentation

See the plugin page and the Explorer feature page in the Quartz documentation.

License

MIT