From 54e722a55d58f4bab86184ffc970159628fa6967 Mon Sep 17 00:00:00 2001
From: freenandes <42041153+freenandes@users.noreply.github.com>
Date: Wed, 18 Oct 2023 02:43:41 +0000
Subject: [PATCH] docs: Update showcase.md (#540)

---
 docs/features/explorer.md |   58 +++++++++++++++++++++++++++++++++++-----------------------
 1 files changed, 35 insertions(+), 23 deletions(-)

diff --git a/docs/features/explorer.md b/docs/features/explorer.md
index 8a9f506..fd656a8 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.
 >
@@ -29,7 +31,7 @@
   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"],
@@ -42,7 +44,7 @@
 
 - Removing table of contents: 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,7 +59,8 @@
 ```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)
+  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
 
@@ -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,32 +146,36 @@
 ```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.
+
+### 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
 
@@ -178,18 +190,18 @@
     if (node.depth > 0) {
       // set emoji for file/folder
       if (node.file) {
-        node.name = "📄 " + node.name
+        node.displayName = "📄 " + node.displayName
       } else {
-        node.name = "📁 " + node.name
+        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 [[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]].
+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({
@@ -224,7 +236,7 @@
 > 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,

--
Gitblit v1.10.0