Skip to main content

Adding resource-level documentation

Added in eventcatalog@3.15.0
Scale plan required

Resource docs require an EventCatalog Scale plan.

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​

Each doc file supports the following frontmatter.

PropertyRequiredDescription
titleNoDisplay name of the doc. Defaults to the file name.
summaryNoShort description shown below the title.
typeNoGroups the doc in the sidebar. Defaults to the folder name, or pages if placed directly in docs/.
versionNoDoc version. Defaults to the resource version.
orderNoExplicit sort position within the group.
badgesNoBadges shown on the doc page.

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​

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​

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

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​

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