Re-document how to use a custom order with explorer

[aubertc]

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: https://github.com/jackyzha0/quartz/commit/e59181c3aa26c2a86b1ce9f501f53a9e3de2908f#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.

[sidney-eliot]

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]

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

[saberzero1]

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]

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]

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]

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 https://github.com/jackyzha0/quartz/commit/e59181c3aa26c2a86b1ce9f501f53a9e3de2908f#diff-f9be51d330ad746884c756fb97a0726708199f0bb733d5dfbc8a4b110b11399bL266-L319 commit). It is probably a typescript limitation on my side, but I wasn't able to debug it so far.

[saberzero1]

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]

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]

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]

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]

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]

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]

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]

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 )