Adding specific navigation node causes build to fail

[milanholemans]

Greetings

Our team maintains an open-source tool called CLI for Microsoft 365. Because we are a CLI tool, we also need documentation. About 6 months ago we moved from MkDocs to Docusaurus and up until now, it's working perfectly.

For every PR created in our repo, we verify if the docs are built without issues. Yesterday we encountered something strange. A contributor of ours created a new PR (pnp/cli-microsoft365#5537) to introduce a new command with associated documentation. We noticed that the docs workflow failed to build, but couldn't really see why this happened.
We pulled the code locally and tried a local build with both npm start and npm run build. Both actions are working perfectly on our local machine.
It's quite annoying that we can't reproduce it locally, but we did some trial & error with the GH build workflow.

The issue occurs when we add a certain navigation node to the sidebar.

{
   "type": "doc",
   "label": "group user list",
   "id": "cmd/aad/group/group-user-list"
}

Our findings at this moment:

• If we move the navigation node to another node group, the build fails.
• If we move from manual ordering to autogenerated ordering, the build fails.
• If we make a tiny adjustment to the id property like cmd/aad/group/group-user-list1 or cmd/aad/group/group-userlist, the build succeeds.
• If we move the page to another folder (e.g. the parent folder, cmd/aad/group-user-list), the build succeeds.
• If we leave the navigation node as it should be, and we remove any other random navigation node from the sidebar, the build succeeds. This can be any navigation node, even a navigation node from another section in the site.

Can someone please help us? At this moment we don't really have an idea what is causing this. Also, the fact that this only occurs in GitHub actions is very odd.

Thank you in advance
The CLI for Microsoft 365 maintainers team

---

Information

Our Docusaurus code: https://github.com/pnp/cli-microsoft365/tree/main/docs/docs
Failing PR: pnp/cli-microsoft365#5537
Failing workflow: https://github.com/pnp/cli-microsoft365/actions/runs/6383089625/job/17341230586
Failing workflow with advanced diagnostics enabled: https://github.com/pnp/cli-microsoft365/actions/runs/6393129410/job/17352061057

[slorber]

Hmmm, weird, that looks like a bug yes.

The only thing I can think of is that we may have a naming conflict in how we emit JSON data bundles, ie 2 docs compete to produce the same json file.

If we make a tiny adjustment to the id property like cmd/aad/group/group-user-list1 or cmd/aad/group/group-userlist, the build succeeds.

Could you try both cases and report what works or doesn't? Because I'm not sure what you did exactly.

• Keep the same file name, and add a different front matter id: xyz + change sidebar id
• Change the filename + sidebar id

[milanholemans]

Unfortunately not sure how I can fix it if we are unable to reproduce consistently

You can easily reproduce it if you clone our repository and add a page docs/docs/cmd/aad/group/group-user-list.mdx.
After that, you should update the sidebars file located at docs/src/config/sidebars.js with the following node:

{
  type: 'doc',
  label: 'group user list',
  id: 'cmd/aad/group/group-user-list'
}

That's it. If you try to build it in a GH pipeline, it breaks.

Are you on Windows? Maybe it only works there?

We tried mainly on Windows, yeah, but we also did one build on Mac. There it works as well. Haven't tried Linux yet but don't know if that's worth trying.

I don't understand how trailingSlash is related to the issue

You are not alone, we don't understand it either. It's very odd that it only happens for this specific page (unless you remove a random other node from the sidebars.js file).

[milanholemans]

@slorber just did the test you asked for.

• Renamed the page to group-user-list-page.
• Added id: group-user-list to the frontmatter of the page.
• Added this page to the sidebars.js.

I can confirm this build succeeds. So it seems like the file name is causing the issue.

[Jwaegebaert]

I've been following this closely as I started the research with @milanholemans but he is doing the most grunt work as of late. Thanks for your assistance already @slorber. It's quite hard to put a finger on the root cause of the issue. But it's very interesting to see that changing the ID in front matter also leads to a successful build. It may be interesting to know that there isn't any other file in the docs folder that is named group-user-list.mdx

[slorber]

I'm sorry but I won't have time to help you much on troubleshooting this. I need to focus on v3 and although it's annoying for you, solving this problem is likely time consuming and will only unlock one Docusaurus user 😅

If you can create a minimal repro of the problem using only Docusaurus core dependencies, removing all the un-necessary things, that would help me help you with a better ROI.

[milanholemans]

If you can create a minimal repro of the problem using only Docusaurus core dependencies, removing all the un-necessary things, that would help me help you with a better ROI.

Because trailingSlash: false unblock us (for now) I think we'll go with that as a solution. As far as I know, this can't hurt to set either. If we run against the same issue, we'll come back to you.