Re-document how to use a custom order with explorer #1983

aubertc · 2025-05-18T19:30:04Z

Is your feature request related to a problem? Please describe.

It used to be the case that an example nameOrderMap record was given as an example on how to impose a non-alphabetical order on the elements of the explorer. This example was deleted with this commit: e59181c#diff-f9be51d330ad746884c756fb97a0726708199f0bb733d5dfbc8a4b110b11399bL266-L319

Describe the solution you'd like

It would be nice to have documented how a custom order can be developed for the explorer, like there was before (e.g. how to have "Poetry Folder" displayed before "Essay Folder" in the explorer)

Describe alternatives you've considered

I have tried to adapt the example myself to the current version of quartz but was unsuccessful. I can share my attempt in more details if that is useful.

Additional context

This "custom order" explorer is used on the website https://princomp.github.io/ that requires a very particular order in its content (the lectures are not numbered, but should be followed in a particular order). I even have an "order" file that I used to automatically create a web-order.ts file that I then import to have the new order seamlessly integrated.

The text was updated successfully, but these errors were encountered:

sidney-eliot · 2025-05-20T07:35:24Z

Hey @aubertc I'm still successfully using the code I created to set a custom order (if you look in the src folder on the main branch of my 3d artists handbook, you can see it in action). I don't see why it wouldn't work anymore, as it's just a simple loop that takes a list to determine the new order in which the outliner structure is created.

sidney-eliot · 2025-05-20T07:38:25Z

But I'm not on the newest quartz version yet, so that might be why.

saberzero1 · 2025-05-20T08:51:50Z

But I'm not on the newest quartz version yet, so that might be why.

You seem to be on 4.1.4. This change was introduced in 4.5.0.

sidney-eliot · 2025-05-20T12:00:49Z

The code logic probably can stay as is and just needs to be adapted to the new variable names (or element item name) or structure that changed. This probably is doable without too much effort or know how.

sidney-eliot · 2025-05-20T12:06:37Z

I have been trying out an alternative, for my 3d artist handbook at least (astro's starlight framework with an obsidian plugin), so I currently won't be updating or touching any of the code in my quartz project for the time being.

aubertc · 2025-05-20T13:00:30Z

Thanks for getting back to me @sidney-eliot , I fully understand. I will try again to re-document this feature, hopefully with more success this time.

@saberzero1 do you have any idea / guidance on what changed that caused this feature not to work anymore? The problem that I am having right now is that the sortFn function, declared as

export const sortFn: Options["sortFn"] = (a, b) => {

cannot seem to be able to access the

    const nameOrderMap: Record<string, number> = {
      "poetry-folder": 100,
      "essay-folder": 200,
      "research-paper-file": 201,
      "dinosaur-fossils-file": 300,
      "other-folder": 400,
    }

const declared in another file (cf. the e59181c#diff-f9be51d330ad746884c756fb97a0726708199f0bb733d5dfbc8a4b110b11399bL266-L319 commit). It is probably a typescript limitation on my side, but I wasn't able to debug it so far.

saberzero1 · 2025-05-20T18:44:02Z

Thanks for getting back to me @sidney-eliot , I fully understand. I will try again to re-document this feature, hopefully with more success this time.

@saberzero1 do you have any idea / guidance on what changed that caused this feature not to work anymore? The problem that I am having right now is that the sortFn function, declared as

export const sortFn: Options["sortFn"] = (a, b) => {

cannot seem to be able to access the
const nameOrderMap: Record<string, number> = {
  "poetry-folder": 100,
  "essay-folder": 200,
  "research-paper-file": 201,
  "dinosaur-fossils-file": 300,
  "other-folder": 400,
}
const declared in another file (cf. the e59181c#diff-f9be51d330ad746884c756fb97a0726708199f0bb733d5dfbc8a4b110b11399bL266-L319 commit). It is probably a typescript limitation on my side, but I wasn't able to debug it so far.

The sort function (and filter function and map function for that matter) are stringified and passed to the explorer.inline.ts file. If you want to use a const from another file, you'd need to import it in explorer.inline.ts for the sort function to be able to access it.

https://github.com/jackyzha0/quartz/blob/v4/quartz%2Fcomponents%2Fscripts%2Fexplorer.inline.ts#L163-L165

aubertc · 2025-05-21T05:30:33Z

Thanks for the indication @saberzero1 but I'm sorry, I still can't make it work… My sortFn function works just fine if I have

// quartz.layout.ts
import { Options } from "./quartz/components/Explorer"

export const sortFn: Options["sortFn"] = (a, b) => {
  const nameOrderMap: Record<string, number> = {
		"docs/index.md": 1,
		"docs/about/index.md": 2,
	}
    return (nameOrderMap[a.data.filePath] || 0)- (nameOrderMap[b.data.filePath] || 0)
  }

But if I try to "split" this function so that the nameOrderMap const is declared in another file (content/web-order), then I cannot make it work. I have

// quartz.layout.ts
import { Options } from "./quartz/components/Explorer"
import { nameOrderMap } from "./content/web-order"

export const sortFn: Options["sortFn"] = (a, b) => {
    return (nameOrderMap[a.data.filePath] || 0)- (nameOrderMap[b.data.filePath] || 0)
  }

// quartz/components/scripts/explorer.inline.ts
import { nameOrderMap } from "../../../content/web-order"

// content/web-order
export const nameOrderMap: Record<string, number> = {
		"docs/index.md": 1,
		"docs/about/index.md": 2,
}

saberzero1 · 2025-05-21T12:25:08Z

Thanks for the indication @saberzero1 but I'm sorry, I still can't make it work… My sortFn function works just fine if I have

// quartz.layout.ts
import { Options } from "./quartz/components/Explorer"

export const sortFn: Options["sortFn"] = (a, b) => {
  const nameOrderMap: Record<string, number> = {
		"docs/index.md": 1,
		"docs/about/index.md": 2,
	}
    return (nameOrderMap[a.data.filePath] || 0)- (nameOrderMap[b.data.filePath] || 0)
  }

But if I try to "split" this function so that the nameOrderMap const is declared in another file (content/web-order), then I cannot make it work. I have

// quartz.layout.ts
import { Options } from "./quartz/components/Explorer"
import { nameOrderMap } from "./content/web-order"

export const sortFn: Options["sortFn"] = (a, b) => {
    return (nameOrderMap[a.data.filePath] || 0)- (nameOrderMap[b.data.filePath] || 0)
  }

// quartz/components/scripts/explorer.inline.ts
import { nameOrderMap } from "../../../content/web-order"

// content/web-order
export const nameOrderMap: Record<string, number> = {
		"docs/index.md": 1,
		"docs/about/index.md": 2,
}

Is there any particular reason why you have the web-order under the content folder? All non-Markdown files under content/ are emitted to the final build. Not sure if we account for that in the build process.

Do you have any errors logged to the browser console?

aubertc · 2025-05-21T13:45:18Z

Is there any particular reason why you have the web-order under the content folder?

The content folder is where "things get build", so it makes some sense in my workflow. I've moved the file to the root folder and updated the path, but it didn't changes anything.

Do you have any errors logged to the browser console?

Nothing relevant, no. And the explorer is empty, so clearly something is not going through.

saberzero1 · 2025-05-21T14:50:15Z

Is there any particular reason why you have the web-order under the content folder?

The content folder is where "things get build", so it makes some sense in my workflow. I've moved the file to the root folder and updated the path, but it didn't changes anything.

Do you have any errors logged to the browser console?

Nothing relevant, no. And the explorer is empty, so clearly something is not going through.

Do you have a public repository, so I can see what your exact setup is?

aubertc · 2025-05-21T14:54:24Z

The version that is currently deployed (that works using a custom order and quartz v.4.0) is at https://github.com/princomp/princomp.github.io/tree/quartz, where the relevant files are

https://github.com/princomp/princomp.github.io/blob/quartz/sortFn.ts
https://princomp.github.io/web-order.ts

The version I am currently working on is hosted at https://github.com/princomp/princomp.github.io/tree/quartz-update (there are only 2 relevant commits, all the history is forked from quartz repo otherwise).

Thanks a lot for looking into it.

saberzero1 · 2025-05-21T15:58:21Z

The version that is currently deployed (that works using a custom order and quartz v.4.0) is at princomp/princomp.github.io@quartz, where the relevant files are

princomp/princomp.github.io@quartz/sortFn.ts princomp.github.io/web-order.ts

The version I am currently working on is hosted at princomp/princomp.github.io@quartz-update (there are only 2 relevant commits, all the history is forked from quartz repo otherwise).

Thanks a lot for looking into it.

The version you're working on has no content directory, is this expected?

aubertc · 2025-05-21T16:10:05Z

Yes, it is built separately (it's a long story ;-) told in part at https://princomp.github.io/docs/about/dev_guide#deploying-locally-the-website )

aubertc added the enhancement New feature or request label May 18, 2025

aubertc mentioned this issue May 19, 2025

Added doc example to explorer sortFn #564

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Re-document how to use a custom order with explorer #1983

Re-document how to use a custom order with explorer #1983

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Re-document how to use a custom order with explorer #1983

Re-document how to use a custom order with explorer #1983

Comments

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!