Finding the real doc ID for index.md in a Docusaurus manual sidebar

Referencing an index.md file in Docusaurus’s manual sidebar (the kind you list explicitly in sidebars.ts) gets surprisingly fiddly once numeric-prefixed directories are involved.

The problem

#

The directory structure looked like this:

docs/01-foundations/01-cryptography/index.md

The obvious-looking candidates were tried, in order, and all of them failed.

// attempt 1
"01-foundations/01-cryptography/index"
// attempt 2
"foundations/cryptography"
// attempt 3
"01-foundations"

Cause and rule

#

Docusaurus derives a sidebar ID with two rules:

1. Numeric prefixes (01-, 02-, …) are stripped from the ID.
2. index.md files keep an /index suffix on the ID.

So the correct ID was:

foundations/cryptography/index

The faster way to find it

#

Instead of guessing frontmatter values, get the autogenerated sidebar to build successfully first, then read the real ID straight out of the build artifacts.

# 1. Temporarily switch sidebars.ts to autogenerated mode and confirm the build succeeds
npm run build

# 2. Read the real doc IDs out of the build output
cat .docusaurus/globalData.json | grep -o '"id":"[^"]*"' | sort -u

Copy whatever ID shows up there straight into the manual sidebar.

One thing to watch

#

Setting a custom id: in frontmatter overrides the rule above entirely. Don’t mix a manual sidebar with custom IDs — the moment they mix, you’re back to debugging from scratch.