# Adding resource-level documentation

Copy as Markdown[View as Markdown](/docs/development/bring-your-own-documentation/resource-docs/adding-resource-docs.md)

***

**Added in** `eventcatalog@3.15.0`

Scale plan required

Resource docs require an [EventCatalog Scale plan](https://eventcatalog.dev/pricing).

## Adding resource-level documentation[​](#adding-resource-level-documentation "Direct link to Adding resource-level documentation")

Place `.mdx` files inside a `docs/` directory under any resource. EventCatalog will automatically pick them up and display them in the resource's sidebar.

```
services/
└── OrdersService/
    ├── index.mdx
    └── docs/
        ├── 01-deployment.mdx
        └── 02-incident-response.mdx
```

### Frontmatter properties[​](#frontmatter-properties "Direct link to Frontmatter properties")

Each doc file supports the following frontmatter.

| Property  | Required | Description                                                                                           |
| --------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `title`   | No       | Display name of the doc. Defaults to the file name.                                                   |
| `summary` | No       | Short description shown below the title.                                                              |
| `type`    | No       | Groups the doc in the sidebar. Defaults to the folder name, or `pages` if placed directly in `docs/`. |
| `version` | No       | Doc version. Defaults to the resource version.                                                        |
| `order`   | No       | Explicit sort position within the group.                                                              |
| `badges`  | No       | Badges shown on the doc page.                                                                         |

#### Example of resource-level documentation[​](#example-of-resource-level-documentation "Direct link to Example of resource-level documentation")

services/OrdersService/docs/01-deployment.mdx

```
---
title: Deployment runbook
summary: Step-by-step guide for deploying the Orders service to production.
version: 1.0.0
---

## Pre-deployment checklist

1. Confirm staging tests pass.
2. Notify the on-call engineer.
...
```

### Order docs with numeric prefixes[​](#order-docs-with-numeric-prefixes "Direct link to Order docs with numeric prefixes")

Files are sorted alphabetically by default. Prefix the file name with a number to control the order.

```
docs/
├── 01-deployment.mdx
├── 02-incident-response.mdx
└── 03-disaster-recovery.mdx
```

The numeric prefix is stripped from the doc's ID and URL, so `01-deployment.mdx` is accessible at `.../pages/deployment`.

You can also set an explicit `order` value in frontmatter, which takes precedence over the numeric prefix.

### Use with domains and subdomains[​](#use-with-domains-and-subdomains "Direct link to Use with domains and subdomains")

Domains and subdomains follow the same pattern.

```
domains/
└── E-Commerce/
    ├── index.mdx
    └── docs/
        └── 01-bounded-context.mdx
    └── subdomains/
        └── Orders/
            ├── index.mdx
            └── docs/
                └── 01-order-processing.mdx
```

## Navigate to a resource doc[​](#navigate-to-a-resource-doc "Direct link to Navigate to a resource doc")

Resource docs are served at:

```
http://localhost:3000/docs/{resourceType}/{resourceId}/{version}/{docType}/{docId}
```

For example, `01-deployment.mdx` for `OrdersService` version `1.0.0` would be at:

```
http://localhost:3000/docs/services/OrdersService/1.0.0/pages/deployment
```

## Grouping docs by type[​](#grouping-docs-by-type "Direct link to Grouping docs by type")

Docs can be organised into groups using subdirectories inside `docs/`. Each subdirectory becomes a **doc type** and gets its own section in the resource sidebar.

```
services/
└── OrdersService/
    ├── index.mdx
    └── docs/
        ├── adrs/
        │   └── 01-use-postgres.mdx
        ├── runbooks/
        │   ├── 01-deployment.mdx
        │   └── 02-incident-response.mdx
        └── guides/
            └── on-call.mdx
```

The folder name is used as the group label by default. The built-in types `adrs`, `runbooks`, `contracts`, `troubleshooting`, and `guides` are automatically formatted with friendly labels in the sidebar.

You can override the type for any doc using the `type` frontmatter field, regardless of which folder it lives in:

services/OrdersService/docs/adrs/01-use-postgres.mdx

```
---
title: Use PostgreSQL for order storage
type: architecture-records
---
```

The type resolution order is:

1. `type` frontmatter — takes highest precedence
2. Folder name — used when `type` is not set
3. `pages` — fallback when the doc is placed directly in `docs/` with no subfolder