docs: add explorer example for advanced sortFn (#564)

* Added doc example to explorer sortFn

* Prettier fixed formatting

* Let Prettier fix the formatting of the entire markdown file

* Updated example

* Added extra commentary and fixed example

* Update docs/features/explorer.md

* doc fixes

* docs: remove leftover TODO

* docs: move example to `advanced`

---------

Co-authored-by: Sidney <85735034+Epicrex@users.noreply.github.com>
Co-authored-by: Jacky Zhao <j.zhao2k19@gmail.com>
Co-authored-by: Ben Schlegel <ben5.schlegel@gmail.com>

docs/features/explorer.md

@@ -179,6 +179,34 @@ Component.Explorer({
 
 ## Advanced examples
 
+> [!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.
+>
+> ```ts title="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
+> }
+> ```
+>
+> You can then import them like this:
+>
+> ```ts title="quartz.layout.ts"
+> 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:
@@ -216,30 +244,63 @@ Notice how we customized the `order` array here. This is done because the defaul
 
 To fix this, we just changed around the order and apply the `sort` function before changing the display names in the `map` function.
 
-> [!tip]
+### Use `sort` with pre-defined sort order
-> 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.
+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.
->
+
-> ```ts title="functions.ts"
+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).
-> import { Options } from "./quartz/components/ExplorerNode"
+
-> export const mapFn: Options["mapFn"] = (node) => {
+```ts title="quartz.layout.ts"
->   // implement your function here
+Component.Explorer({
-> }
+  sortFn: (a, b) => {
-> export const filterFn: Options["filterFn"] = (node) => {
+    const nameOrderMap: Record<string, number> = {
->   // implement your function here
+      "poetry-folder": 100,
-> }
+      "essay-folder": 200,
-> export const sortFn: Options["sortFn"] = (a, b) => {
+      "research-paper-file": 201,
->   // implement your function here
+      "dinosaur-fossils-file": 300,
-> }
+      "other-folder": 400,
-> ```
+    }
->
+
-> You can then import them like this:
+    let orderA = 0
->
+    let orderB = 0
-> ```ts title="quartz.layout.ts"
+
-> import { mapFn, filterFn, sortFn } from "./functions.ts"
+    if (a.file && a.file.slug) {
-> Component.Explorer({
+      orderA = nameOrderMap[a.file.slug] || 0
->   mapFn: mapFn,
+    } else if (a.name) {
->   filterFn: filterFn,
+      orderA = nameOrderMap[a.name] || 0
->   sortFn: sortFn,
+    }
-> })
+
-> ```
+    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
+```