Sidebar Ordering

How Docusaurus decides the order of items in the left sidebar. Lower number = higher up. Two mechanisms, depending on whether the item is a folder or a standalone doc.

The two knobs

Item type	Where the number lives	Field
A folder (category)	_category_.json in that folder	position
A standalone doc	the doc's frontmatter	sidebar_position

Each folder is its own list. Items only compete for a number when they share the same parent — so position: 5 in two different folders is fine, but two siblings both at 5 will clash and order unpredictably.

Category folder — _category_.json

{
  "label": "🛠 Tooling",
  "position": 3,
  "link": {
    "type": "generated-index",
    "description": "Developer tooling notes — setup, configuration, and workflow tips."
  }
}

• link.type: "generated-index" — auto-builds a landing page listing the folder's docs. This is the usual choice for a category.
• link.type: "doc" — instead points the category link at one specific document (by its doc ID). Use when you have a hand-written intro page for the section.

Standalone doc — frontmatter

---
title: Start Here
sidebar_position: 1
---

sidebar_position: 0 pins a doc to the very top of its group (lowest number wins) — handy for an intro/landing doc.

Full ordering map

Legend: DIR = category folder (position in _category_.json), doc = standalone page (sidebar_position in frontmatter), – = no position set (falls back to alphabetical).

Top level — docs/

pos	kind	item
1	doc	intro.md
2	DIR	🤖 AI Engineering
3	DIR	🛠 Tooling
4	DIR	🚀 Projects
5	DIR	🎓 Courses
6	DIR	🏢 EDB
7	DIR	🗄️ Databases

Non-AI topic categories (Databases, and later Backend, Frontend, Languages, …) are added under docs/ as their first note arrives — see FILING-NOTES.md.

🤖 AI Engineering — docs/ai/

pos	kind	item
1	doc	start-here.md
2	DIR	📚 Knowledge Bank (knowledge-bank/)
3	DIR	🧪 Learnings (learnings/)
4	doc	glossary.md
5	doc	building-an-agentic-system.md
6	doc	ai-first-methodology.md
7	doc	reading-list.md
8	doc	open-questions.md
9	doc	ASSISTANT_PROMPT.md

Inside knowledge-bank/ (category links to the overview doc):

pos	kind	item
0	doc	00-overview.md
1	doc	01-foundations.md
2	doc	02-intermediate.md
3	doc	03-expert.md

Inside learnings/ — one flat folder, one file per learning (overview.md pinned at sidebar_position: 0, the rest alphabetical). No sub-folders.

🛠 Tooling — docs/tooling/

pos	kind	item
1	doc	sidebar-ordering.md
–	DIR	devcontainers/

devcontainers/ has no position, so it sorts after positioned items by name.

🚀 Projects — docs/projects/

pos	kind	item
1	DIR	Shortcut AI Agent (shortcut-ai-agent/)

🎓 Courses — docs/courses/

pos	kind	item
1	DIR	Google × Kaggle GenAI (google-kaggle-genai/)

Inside google-kaggle-genai/:

pos	kind	item
0	doc	index.md (pinned to top)
1	doc	agents.md

🏢 EDB — docs/edb/

pos	kind	item
1	doc	start-here.md
2	doc	glossary.md
3	DIR	Systems & Applications (systems/)
4	DIR	Domain & Business (domain/)
5	DIR	Flows & Processes (flows/)
6	DIR	Data Patch Agent (data-patch-agent/)

Inside EDB subfolders (each has a single note for now):

folder	pos	doc
systems/	—	(no docs yet)
domain/	1	cost-categories.md
flows/	1	subform-gctemplate.md
data-patch-agent/	–	notes.md

Gotchas

• Same-level collisions are the usual bug: two siblings on the same number. Keep siblings on a clean 1, 2, 3, … sequence.
• Positions don't need to be unique across different folders — only within a single parent.
• If nothing sets a position, Docusaurus falls back to alphabetical order.