How we structure things

Global structure

Think of the docs like a bookshelf:

Each category is a shelf (e.g. csharp-guides)
Each Markdown file is a book on that shelf (e.g. dependency-injection-patterns.md)
Each image lives in the /img folder inside its category

All folders and files should use kebab-case:

✅ csharp-guides/intro.md
✅ angular-guides/component-testing.md
❌ CSharpGuides/introPage.md
❌ angular_guides/ComponentTesting.md

Inside each category folder, add an /img subfolder for images:

docs/csharp-guides/intro.md
docs/csharp-guides/dependency-injection-patterns.md
docs/csharp-guides/img/service-lifetime-diagram.png

Creating a category

In this project, there is one official way to create a category:
every category must link to an intro.md page via a _category_.json file.
No other pattern is allowed.

To create a category, add a _category_.json file inside the folder.

For example, inside docs/csharp-guides/_category_.json:

_category_.json
{
  "label": "C# Guides",
  "position": 2,
  "link": {
    "type": "doc",
    "id": "csharp-guides/intro"
  }
}

What this configuration means:

label: How the category appears in the sidebar
position: Where the category appears relative to other categories
link.id: The doc that opens when someone clicks the category name
(always the intro.md of that category in our project)

Creating a new doc

Every Markdown file can have a sidebar position and should have a title. Sidebar position dictates the order of a category's docs and it isn't always necessary.

Create a new file, for example:
- docs/angular-guides/state-management-basics.md
Add this at the very top (optional):
state-management-basics.md
```
---
sidebar_position: 1
---
```
Then add a first-level header for the title and capitalized only the first letter:
state-management-basics.md
```
# State management basics
```
Now write your content below using normal Markdown.

If you need multiple docs in the same category, just adjust sidebar_position so they appear in the order you want (1, 2, 3, …).

Sub-categories (optional, but powerful)

You can create sub-categories simply by adding sub-folders:

docs/angular-guides/routing/intro.md
docs/angular-guides/routing/_category_.json
docs/angular-guides/routing/img/lazy-loading-example.png

Each sub-category gets its own _category_.json and works the same way as a top-level category.

Adding images

Put images under the /img folder inside the relevant category:
- docs/csharp-guides/img/middleware-pipeline.png

Use them in Markdown like this:

![Middleware pipeline](./img/middleware-pipeline.png)

If you move a doc to another category, remember to move its images too so the relative paths still work.

Summary

For now, just remember:

Use kebab-case for all folders and files
Start every doc with a # Title and an optional sidebar_position
Use _category_.json to define categories and their intro docs
Keep images under /img inside each category

Global structure​

Creating a category​

Creating a new doc​

Sub-categories (optional, but powerful)​

Adding images​

Summary​