Docz: Order of documents vary between development and production builds

[Swapnull]

Bug Report

Describe the bug

The order of the menu is different between the development and production version of the same set of files.

Development Version

Production Version

From what I can see, it is based on the file names rather than the order. My file structure looks like

but when I change the folder names to be 1-brand and 2-atoms they order correctly. To then get the documents to arrange correctly, I have to do the order ascending (without setting the order: 'ascending' option as that does nothing) and then work with it looking strange in the dev version

• OS: OSX 10.3.4
• Node/npm version: 10.1.0/5.6.0

[mAAdhaTTah]

Generally speaking, the menu ordering logic could use some work. We're kind of stuck with a few suboptimal solutions (order config, prefixing with numbers, etc.) that limits the amount of control / flexibility over the menu order. We need a better API for this overall.

[pedronauck]

Which version do you're using @Swapnull ?

[pedronauck]

Do you have some idea about that feature @mAAdhaTTah ?

[mAAdhaTTah]

Do you have some idea about that feature @mAAdhaTTah ?

I think defining the menu & submenu items via a multi-dimensional array, rather in the front-matter of the pages, would be better. The annoying thing is wanting to rearrange the location of a page on the list and needing to change _every single page_ in order to get it into the right place.

First thought is something like this:

// doczrc.js
export default {
  menu: [
    ["Introduction", ["quickstart", "changelog"]]
    ["Walkthrough", ["setup", "deploying"]]
  ]
};

Even better if we could maybe import the files:

// doczrc.js
import quicksart from './docs/quickstart.mdx';

export default {
  menu: [
    ["Introduction", [quickstart]]
    // etc.
  ]
};

Thoughts?

[pedronauck]

Can be a good choice, but I have some points:

• I think that an array of objects can be a better solution in this case
• Import .mdx directly can be bad because we'll need to transpile they after import to read and this can be a performance leaky

Another solution that I'm thinking about is using an export const instead of a front matter to define document settings, so we can easily import the menu and using on the definition, like that:

// src/components/index.js
export const menu = {
  name: 'Components',
  order: 1
}

// docs/components/Alert.mdx
import { menu } from 'src/components'

export const meta = {
  menu,
  name: 'Alert',
  order: 2,
}

What do you thinking about that @mAAdhaTTah?

[mAAdhaTTah]

With that setup, you still have the "need to touch every page in order to rearrange" problem. The problem isn't the use of frontmatter, it's with storing the ordering data in each .mdx file.

The importing .mdx was just a thought, not a requirement. If it's too heavy, the first option would work fine.

[Swapnull]

@pedronauck I am using version 0.5.9.

This bug is not about the architectural decisions of the order, it is about the fact that when built in production mode, the order is totally forgotten and the pages are ordered alphabetically. I would expect the development build and production build to look exactly the same, but perform better.

That been said, I agree that the ordering should be something more like a 2d array so you can just get rid of the entire 'order' as a number idea, which can get super annoying if you are trying to add a page in the middle of a large folder. if you have 30 atoms and want to add one in at position 3, you have to change 27 numbers to achieve that.

[pedronauck]

Please @Swapnull, can you update your docz version to v0.6.0 to see if this difference between production and development is fixed? We were with some bugs on build command!

I liked your option @mAAdhaTTah, I'll do that feature in the near future. Unfortunately, right now, my time is tightly tight and I'm focused on trying to solve the main bugs, but then I'll do that!

[pedronauck]

@mAAdhaTTah @Swapnull

To follow the protocol, I'll close this issue in favor of the post on our roadmap that talk about that. Please give us your vote there 🙏

🔀 Managing menu order on default theme

[sanshuiwang]

Can be a good choice, but I have some points:

• I think that an array of objects can be a better solution in this case
• Import .mdx directly can be bad because we'll need to transpile they after import to read and this can be a performance leaky

Another solution that I'm thinking about is using an export const instead of a front matter to define document settings, so we can easily import the menu and using on the definition, like that:

// src/components/index.js
export const menu = {
  name: 'Components',
  order: 1
}

// docs/components/Alert.mdx
import { menu } from 'src/components'

export const meta = {
  menu,
  name: 'Alert',
  order: 2,
}

What do you thinking about that @mAAdhaTTah?

order is sort menus