From 9c8fec06d2b58e4e3bbe280ddc665a99fcc4878c Mon Sep 17 00:00:00 2001
From: Jacky Zhao <j.zhao2k19@gmail.com>
Date: Sun, 09 Mar 2025 22:33:15 +0000
Subject: [PATCH] feat: support non-singleton search
---
docs/features/explorer.md | 204 ++++++++++++++++++++++++++++++++++++--------------
1 files changed, 145 insertions(+), 59 deletions(-)
diff --git a/docs/features/explorer.md b/docs/features/explorer.md
index 8a9f506..95878f7 100644
--- a/docs/features/explorer.md
+++ b/docs/features/explorer.md
@@ -8,6 +8,8 @@
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 | 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.
>
@@ -24,12 +26,12 @@
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
+ useSavedState: true, // whether 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: undefined,
+ filterFn: filterFn: (node) => node.name !== "tags", // filters out 'tags' folder
mapFn: undefined,
// what order to apply functions in
order: ["filter", "map", "sort"],
@@ -40,9 +42,9 @@
Want to customize it even more?
-- Removing table of contents: remove `Component.Explorer()` from `quartz.layout.ts`
+- Removing explorer: remove `Component.Explorer()` from `quartz.layout.ts`
- (optional): After removing the explorer component, you can move the [[table of contents | Table of Contents]] component back to the `left` part of the layout
-- Changing `sort`, `filter` and `map` behavior: explained in [[explorer#Advanced customization]]
+- Changing `sort`, `filter` and `map` behavior: explained in [[#Advanced customization]]
- Component:
- Wrapper (Outer component, generates file tree, etc): `quartz/components/Explorer.tsx`
- Explorer node (recursive, either a folder or a file): `quartz/components/ExplorerNode.tsx`
@@ -57,8 +59,9 @@
```ts title="quartz/components/ExplorerNode.tsx" {2-5}
export class FileNode {
children: FileNode[] // children of current node
- name: string // name of node (only useful for folders)
- file: QuartzPluginData | null // set if node is a file, see `QuartzPluginData` for more detail
+ name: string // last part of slug
+ displayName: string // what actually should be displayed in the explorer
+ file: QuartzPluginData | null // if node is a file, this is the file's metadata. See `QuartzPluginData` for more detail
depth: number // depth of current node
... // rest of implementation
@@ -72,7 +75,12 @@
Component.Explorer({
sortFn: (a, b) => {
if ((!a.file && !b.file) || (a.file && b.file)) {
- return a.name.localeCompare(b.name)
+ // 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
@@ -85,7 +93,7 @@
---
-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 [[explorer#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.
+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.
For more information on how to use `sort`, `filter` and `map`, you can check [Array.prototype.sort()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort), [Array.prototype.filter()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter) and [Array.prototype.map()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map).
@@ -120,7 +128,7 @@
Component.Explorer({
sortFn: (a, b) => {
if ((!a.file && !b.file) || (a.file && b.file)) {
- return a.name.localeCompare(b.name)
+ return a.displayName.localeCompare(b.displayName)
}
if (a.file && !b.file) {
return -1
@@ -138,72 +146,52 @@
```ts title="quartz.layout.ts"
Component.Explorer({
mapFn: (node) => {
- node.name = node.name.toUpperCase()
+ node.displayName = node.displayName.toUpperCase()
},
})
```
### Remove list of elements (`filter`)
-Using this example, you can remove elements from your explorer by providing a list of folders/files using the `list` array.
+Using this example, you can remove elements from your explorer by providing an array of folders/files using the `omit` set.
```ts title="quartz.layout.ts"
Component.Explorer({
filterFn: (node) => {
- // list containing names of everything you want to filter out
- const list = ["authoring content", "building your", "tags", "hosting"]
-
- for (let listNodeName of list) {
- if (listNodeName.toLowerCase() === node.name.toLowerCase()) {
- return false // Found a match, so return false to filter out the node
- }
- }
- return true // No match found, so return true to keep the 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 `list` array. Simply add all folder or file names you want to remove to the array (case insensitive).
+You can customize this by changing the entries of the `omit` set. Simply add all folder or file names you want to remove.
+
+### Remove files by tag
+
+You can access the frontmatter of a file by `node.file?.frontmatter?`. This allows you to filter out files based on their frontmatter, for example by their tags.
+
+```ts title="quartz.layout.ts"
+Component.Explorer({
+ filterFn: (node) => {
+ // exclude files with the tag "explorerexclude"
+ return node.file?.frontmatter?.tags?.includes("explorerexclude") !== true
+ },
+})
+```
+
+### Show every element in explorer
+
+To override the default filter function that removes the `tags` folder from the explorer, you can set the filter function to `undefined`.
+
+```ts title="quartz.layout.ts"
+Component.Explorer({
+ filterFn: undefined, // apply no filter function, every file and folder will visible
+})
+```
## Advanced examples
-### Add emoji prefix
-
-To add emoji prefixes (๐ for folders, ๐ for files), you could use a map function like this:
-
-```ts title="quartz.layout.ts"
-Component.Explorer({
- mapFn: (node) => {
- // dont change name of root node
- if (node.depth > 0) {
- // set emoji for file/folder
- if (node.file) {
- node.name = "๐ " + node.name
- } else {
- node.name = "๐ " + node.name
- }
- }
- },
-}})
-```
-
-### Putting it all together
-
-In this example, we're going to customize the explorer by using functions from examples above to [[explorer#Add emoji prefix | add emoji prefixes]], [[explorer#remove-list-of-elements-filter| filter out some folders]] and [[explorer#use-sort-to-put-files-first | sort with files above folders]].
-
-```ts title="quartz.layout.ts"
-Component.Explorer({
- filterFn: sampleFilterFn,
- mapFn: sampleMapFn,
- sortFn: sampleSortFn,
- order: ["filter", "sort", "map"],
-})
-```
-
-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.
@@ -224,10 +212,108 @@
> You can then import them like this:
>
> ```ts title="quartz.layout.ts"
-> import { mapFn, filterFn, sortFn } from "./path/to/your/functions"
+> import { mapFn, filterFn, sortFn } from "./functions.ts"
> Component.Explorer({
> mapFn: mapFn,
> filterFn: filterFn,
> sortFn: sortFn,
> })
> ```
+
+### Add emoji prefix
+
+To add emoji prefixes (๐ for folders, ๐ for files), you could use a map function like this:
+
+```ts title="quartz.layout.ts"
+Component.Explorer({
+ mapFn: (node) => {
+ // dont change name of root node
+ if (node.depth > 0) {
+ // set emoji for file/folder
+ if (node.file) {
+ node.displayName = "๐ " + node.displayName
+ } else {
+ node.displayName = "๐ " + node.displayName
+ }
+ }
+ },
+})
+```
+
+### Putting it all together
+
+In this example, we're going to customize the explorer by using functions from examples above to [[#Add emoji prefix | add emoji prefixes]], [[#remove-list-of-elements-filter| filter out some folders]] and [[#use-sort-to-put-files-first | sort with files above folders]].
+
+```ts title="quartz.layout.ts"
+Component.Explorer({
+ filterFn: sampleFilterFn,
+ mapFn: sampleMapFn,
+ sortFn: sampleSortFn,
+ order: ["filter", "sort", "map"],
+})
+```
+
+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.
+
+### Use `sort` with pre-defined sort order
+
+Here's another example where a map containing file/folder names (as slugs) is used to define the sort order of the explorer in quartz. All files/folders that aren't listed inside of `nameOrderMap` will appear at the top of that folders hierarchy level.
+
+It's also worth mentioning, that the smaller the number set in `nameOrderMap`, the higher up the entry will be in the explorer. Incrementing every folder/file by 100, makes ordering files in their folders a lot easier. Lastly, this example still allows you to use a `mapFn` or frontmatter titles to change display names, as it uses slugs for `nameOrderMap` (which is unaffected by display name changes).
+
+```ts title="quartz.layout.ts"
+Component.Explorer({
+ sortFn: (a, b) => {
+ const nameOrderMap: Record<string, number> = {
+ "poetry-folder": 100,
+ "essay-folder": 200,
+ "research-paper-file": 201,
+ "dinosaur-fossils-file": 300,
+ "other-folder": 400,
+ }
+
+ let orderA = 0
+ let orderB = 0
+
+ if (a.file && a.file.slug) {
+ orderA = nameOrderMap[a.file.slug] || 0
+ } else if (a.name) {
+ orderA = nameOrderMap[a.name] || 0
+ }
+
+ if (b.file && b.file.slug) {
+ orderB = nameOrderMap[b.file.slug] || 0
+ } else if (b.name) {
+ orderB = nameOrderMap[b.name] || 0
+ }
+
+ return orderA - orderB
+ },
+})
+```
+
+For reference, this is how the quartz explorer window would look like with that example:
+
+```
+๐ Poetry Folder
+๐ Essay Folder
+ โ๏ธ Research Paper File
+๐ฆด Dinosaur Fossils File
+๐ฎ Other Folder
+```
+
+And this is how the file structure would look like:
+
+```
+index.md
+poetry-folder
+ index.md
+essay-folder
+ index.md
+ research-paper-file.md
+dinosaur-fossils-file.md
+other-folder
+ index.md
+```
--
Gitblit v1.10.0