# Diagrams reference

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

***

This page lists the fields, paths, and routes supported by diagrams.

## Paths[​](#paths "Direct link to Paths")

Diagrams can be created in any `diagrams` folder:

```
/diagrams/{Diagram Name}/index.mdx
/domains/{Domain Name}/diagrams/{Diagram Name}/index.mdx
/systems/{System Name}/diagrams/{Diagram Name}/index.mdx
```

Versioned diagrams use:

```
/diagrams/{Diagram Name}/versioned/{version}/index.mdx
```

## Routes[​](#routes "Direct link to Routes")

| Route                                   | Description                 |
| --------------------------------------- | --------------------------- |
| `/docs/diagrams/{diagram-id}/{version}` | Diagram documentation page. |

## Required fields[​](#required-fields "Direct link to Required fields")

### `id`[​](#id "Direct link to id")

* Type: `string`

Unique id of the diagram. EventCatalog uses this for URLs and resource references.

Example

```
---
id: checkout-sequence
---
```

### `name`[​](#name "Direct link to name")

* Type: `string`

Display name of the diagram.

Example

```
---
name: Checkout Sequence
---
```

### `version`[​](#version "Direct link to version")

* Type: `string`

Version of the diagram documentation.

Example

```
---
version: 1.0.0
---
```

## Optional fields[​](#optional-fields "Direct link to Optional fields")

### `summary`[​](#summary "Direct link to summary")

* Type: `string`

Short description of the diagram.

Example

```
---
summary: Sequence diagram for checkout orchestration.
---
```

### `owners`[​](#owners "Direct link to owners")

* Type: `array`

An array of team or user ids that own the diagram.

Example

```
---
owners:
  - checkout-platform
---
```

### `badges`[​](#badges "Direct link to badges")

* Type: `array`

Badges rendered on the diagram page.

Example

```
---
badges:
  - content: Mermaid
    backgroundColor: blue
    textColor: blue
---
```

### `repository`[​](#repository "Direct link to repository")

* Type: `object`

Repository metadata for the diagram.

Example

```
---
repository:
  url: https://github.com/acme/architecture
---
```

### `attachments`[​](#attachments "Direct link to attachments")

* Type: `array`

External links or supporting documents attached to the diagram.

Example

```
---
attachments:
  - title: Source diagram
    url: https://miro.com/app/board/example
    type: miro
---
```

## Content[​](#content "Direct link to Content")

Diagram pages can contain any MDX supported by EventCatalog, including Mermaid, PlantUML, Miro, IcePanel, Lucid, Draw\.io, FigJam, images, and normal markdown.