Quartz features an explorer that allows you to navigate all files and folders on your site. It supports nested folders and is highly customizable.
By default, it shows all folders and files on your page. To display the explorer in a different spot, you can edit the layout.
Display names for folders get determined by the title frontmatter field in folder/index.md (more detail in Authoring Content). If this file does not exist or does not contain frontmatter, the local folder name will be used instead.
Info
The explorer uses local storage by default to save the state of your explorer. This is done to ensure a smooth experience when navigating to different pages.
To clear/delete the explorer state from local storage, delete the fileTree entry (guide on how to delete a key from local storage in chromium based browsers can be found here). You can disable this by passing useSavedState: false as an argument.
Most configuration can be done by passing in options to Component.Explorer().
For example, here’s what the default configuration looks like:
quartz.layout.ts
Component.Explorer({ title: "Explorer", // title of the explorer component folderClickBehavior: "collapse", // what happens when you click a folder ("link" to navigate to folder page on click or "collapse" to collapse folder on click) folderDefaultState: "collapsed", // default state of folders ("collapsed" or "open") useSavedState: true, // wether to use local storage to save "state" (which folders are opened) of explorer // Sort order: folders first, then files. Sort folders and files alphabetically sortFn: (a, b) => { ... // default implementation shown later }, filterFn: filterFn: (node) => node.name !== "tags", // filters out 'tags' folder mapFn: undefined, // what order to apply functions in order: ["filter", "map", "sort"],})
When passing in your own options, you can omit any or all of these fields if you’d like to keep the default value for that field.
Want to customize it even more?
Removing table of contents: remove Component.Explorer() from quartz.layout.ts
(optional): After removing the explorer component, you can move the Table of Contents component back to the left part of the layout
This component allows you to fully customize all of its behavior. You can pass a custom sort, filter and map function.
All functions you can pass work with the FileNode class, which has the following properties:
quartz/components/ExplorerNode.tsx
export class FileNode { children: FileNode[] // children of current node name: string // last part of slug displayName: string // what actually should be displayed in the explorer file: QuartzPluginData | null // set if node is a file, see `QuartzPluginData` for more detail depth: number // depth of current node ... // rest of implementation}
Every function you can pass is optional. By default, only a sort function will be used:
Default sort function
// Sort order: folders first, then files. Sort folders and files alphabeticallyComponent.Explorer({ sortFn: (a, b) => { if ((!a.file && !b.file) || (a.file && b.file)) { // sensitivity: "base": Only strings that differ in base letters compare as unequal. Examples: a ≠ b, a = á, a = A // numeric: true: Whether numeric collation should be used, such that "1" < "2" < "10" return a.displayName.localeCompare(b.displayName, undefined, { numeric: true, sensitivity: "base", }) } if (a.file && !b.file) { return 1 } else { return -1 } },})
You can pass your own functions for sortFn, filterFn and mapFn. All functions will be executed in the order provided by the order option (see Customization). These functions behave similarly to their Array.prototype counterpart, except they modify the entire FileNode tree in place instead of returning a new one.
Using this example, you can remove elements from your explorer by providing an array of folders/files using the omit set.
quartz.layout.ts
Component.Explorer({ filterFn: (node) => { // set containing names of everything you want to filter out const omit = new Set(["authoring content", "tags", "hosting"]) return !omit.has(node.name.toLowerCase()) },})
You can customize this by changing the entries of the omit set. Simply add all folder or file names you want to remove.
Notice how we customized the order array here. This is done because the default order applies the sort function last. While this normally works well, it would cause unintended behavior here, since we changed the first characters of all display names. In our example, sort would be applied based off the emoji prefix instead of the first real character.
To fix this, we just changed around the order and apply the sort function before changing the display names in the map function.
Tip
When writing more complicated functions, the layout file can start to look very cramped.
You can fix this by defining your functions in another file.
functions.ts
import { Options } from "./quartz/components/ExplorerNode"export const mapFn: Options["mapFn"] = (node) => { // implement your function here}export const filterFn: Options["filterFn"] = (node) => { // implement your function here}export const sortFn: Options["sortFn"] = (a, b) => { // implement your function here}