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>

authored by

Sidney

Jacky Zhao

Ben Schlegel and committed by

GitHub 2 years ago e1b6a001 233d4b2f

+88 -27

1 changed file

expand all

docs

features

explorer.md

+88 -27

docs/features/explorer.md

··· 179 179 180 180 ## Advanced examples 181 181 182 + > [!tip] 183 + > When writing more complicated functions, the `layout` file can start to look very cramped. 184 + > You can fix this by defining your functions in another file. 185 + > 186 + > ```ts title="functions.ts" 187 + > import { Options } from "./quartz/components/ExplorerNode" 188 + > export const mapFn: Options["mapFn"] = (node) => { 189 + > // implement your function here 190 + > } 191 + > export const filterFn: Options["filterFn"] = (node) => { 192 + > // implement your function here 193 + > } 194 + > export const sortFn: Options["sortFn"] = (a, b) => { 195 + > // implement your function here 196 + > } 197 + > ``` 198 + > 199 + > You can then import them like this: 200 + > 201 + > ```ts title="quartz.layout.ts" 202 + > import { mapFn, filterFn, sortFn } from "./functions.ts" 203 + > Component.Explorer({ 204 + > mapFn: mapFn, 205 + > filterFn: filterFn, 206 + > sortFn: sortFn, 207 + > }) 208 + > ``` 209 + 182 210 ### Add emoji prefix 183 211 184 212 To add emoji prefixes (📁 for folders, 📄 for files), you could use a map function like this: ··· 216 244 217 245 To fix this, we just changed around the order and apply the `sort` function before changing the display names in the `map` function. 218 246 219 - > [!tip] 220 - > When writing more complicated functions, the `layout` file can start to look very cramped. 221 - > You can fix this by defining your functions in another file. 222 - > 223 - > ```ts title="functions.ts" 224 - > import { Options } from "./quartz/components/ExplorerNode" 225 - > export const mapFn: Options["mapFn"] = (node) => { 226 - > // implement your function here 227 - > } 228 - > export const filterFn: Options["filterFn"] = (node) => { 229 - > // implement your function here 230 - > } 231 - > export const sortFn: Options["sortFn"] = (a, b) => { 232 - > // implement your function here 233 - > } 234 - > ``` 235 - > 236 - > You can then import them like this: 237 - > 238 - > ```ts title="quartz.layout.ts" 239 - > import { mapFn, filterFn, sortFn } from "./functions.ts" 240 - > Component.Explorer({ 241 - > mapFn: mapFn, 242 - > filterFn: filterFn, 243 - > sortFn: sortFn, 244 - > }) 245 - > ``` 247 + ### Use `sort` with pre-defined sort order 248 + 249 + 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. 250 + 251 + 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). 252 + 253 + ```ts title="quartz.layout.ts" 254 + Component.Explorer({ 255 + sortFn: (a, b) => { 256 + const nameOrderMap: Record<string, number> = { 257 + "poetry-folder": 100, 258 + "essay-folder": 200, 259 + "research-paper-file": 201, 260 + "dinosaur-fossils-file": 300, 261 + "other-folder": 400, 262 + } 263 + 264 + let orderA = 0 265 + let orderB = 0 266 + 267 + if (a.file && a.file.slug) { 268 + orderA = nameOrderMap[a.file.slug] || 0 269 + } else if (a.name) { 270 + orderA = nameOrderMap[a.name] || 0 271 + } 272 + 273 + if (b.file && b.file.slug) { 274 + orderB = nameOrderMap[b.file.slug] || 0 275 + } else if (b.name) { 276 + orderB = nameOrderMap[b.name] || 0 277 + } 278 + 279 + return orderA - orderB 280 + }, 281 + }) 282 + ``` 283 + 284 + For reference, this is how the quartz explorer window would look like with that example: 285 + 286 + ``` 287 + 📖 Poetry Folder 288 + 📑 Essay Folder 289 + ⚗️ Research Paper File 290 + 🦴 Dinosaur Fossils File 291 + 🔮 Other Folder 292 + ``` 293 + 294 + And this is how the file structure would look like: 295 + 296 + ``` 297 + index.md 298 + poetry-folder 299 + index.md 300 + essay-folder 301 + index.md 302 + research-paper-file.md 303 + dinosaur-fossils-file.md 304 + other-folder 305 + index.md 306 + ```

Configure Feed

Configure Feed