---
sidebar_position: 1
keywords:
- EventCatalog global documentation
sidebar_label: Adding global documentation
title: Adding global documentation
description: Adding global documentation to your EventCatalog
---

import AddedIn from '@site/src/components/MDX/AddedIn';

<AddedIn version="2.33.0" />

## Getting started

Global documentation requires a [Starter or Scale plan](https://eventcatalog.dev/pricing), you can get a 14 day free trial to test it out at [EventCatalog Cloud](https://eventcatalog.cloud). Once you have a license key you can start to use the feature.

## Adding global documentation

Global documentation is split into two parts:

1. [Creating your documentation (markdown files)](#creating-your-documentation)
2. [Configuring your sidebar (eventcatalog.config.js)](#configuring-your-sidebar)

### Creating documentation

Global documentation is stored in the `/docs` folder in your catalog [(see example on GitHub)](https://github.com/event-catalog/eventcatalog/tree/main/examples/default/docs), and can be accessed via the url `/docs/custom/`.

All documentation is a `.mdx` (markdown extended) file. You can organize these however you want, for example:

```
docs/
├── architecture-decision-records/
│   ├── drafts/
│   │   ├── 01-introduction.mdx
│   │   ├── 02-example-record.mdx
│   ├── published/
│   │   ├── 01-introduction.mdx
│   │   ├── 02-example-record.mdx
│   ├── examples/
│   │   ├── 01-introduction.mdx
│   │   ├── 02-example-record.mdx
├── runbooks/
│   ├── 01-introduction.mdx
│   ├── 02-deployment-procedure.mdx
│   ├── 03-disaster-recovery.mdx
│   ├── 04-incident-response.mdx

```

In this example we have global documentation for:

- architecture Decision Records
- Runbooks

:::tip Organize your global documentation
We added numbers (01, 02, 03) to the files to help with maintenance, you can configure the order of the files in your configuration.
:::


#### Structure of markdown files for global documentation

Each markdown file is split into two parts:

1. The frontmatter (properties at the top of the file)
2. The content (the rest of the file)

```mdx
---
title: Architecture decision records
summary: A comprehensive guide to creating new microservices at FlowMart following our best practices and standards
owners: 
  - dboyne
badges:
  - content: 'Guide'
    backgroundColor: 'teal'
    textColor: 'teal'
---

This is your content for your file.

```

**Frontmatter properties**

| Property | Required | Description |
|----------|----------|-------------|
| `title` | Yes | The title of the page |
| `summary` | Yes | A summary of the page |
| `slug` | No | Ability to override the slug (url) of the page |
| `owners` | No | Owners of the page (EventCatalog owners) |
| `badges` | No | The badges of the page |

#### Sidebar configuration

You need to configure the sidebar to include your custom documentation, we do this by using the `customDocs` property in your `eventcatalog.config.js` file.

We have two options for the sidebar:

1. Manually map files and paths to the sidebar
2. Use the autogenerated option to generate the sidebar items

:::tip Autogenerated sidebar
The autogenerated sidebar is the easiest option, it will render all the files in the directory and subdirectories.
If you want to choose which files and order they are displayed in, you can manually map the files and paths to the sidebar.
:::

```js
export default {
  // rest of your config
  customDocs: {
    sidebar: [
      {
        label: 'architecture Decision Records',
        badge: {
          text: 'New', color: 'green'
        },
        collapsed: false,
        items: [
          {
            // Here we map the directory, and use autogenerated to generate the sidebar items
            // Any item added to the folder will be rendered automatically in EventCatalog
            label: 'Drafts', autogenerated: { directory: '/architecture-decision-records/drafts' }
          },
          {
            label: 'Published', autogenerated: { directory: '/architecture-decision-records/published' }
          },
          {
            label: 'Examples', autogenerated: { directory: '/architecture-decision-records/examples' }
          }
        ]
      },
      {
        label: 'Runbooks',
        badge: {
          text: 'New', color: 'green'
        },
        collapsed: false,
        items: [
          {
            // Here we create custom pages in the sidebar
            // We can manually map the slug to a file, or use the autogenerated to generate the sidebar items
            label: 'Creating a new runbook', items: [
              { label: 'Introduction', slug: 'runbooks/01-introduction' },
              { label: 'Deployment Procedure', slug: 'runbooks/02-deployment-procedure' },
              { label: 'Disaster Recovery', slug: 'runbooks/03-disaster-recovery' },
              { label: 'Incident Response', slug: 'runbooks/04-incident-response' },
            ]
          },
        ]
      }
    ]
  }
};
 ```


#### Rendered output

The rendered output will be the content of the markdown file, with the frontmatter properties.

![Example](./img/custom-docs.png)
<a class="block" href="https://demo.eventcatalog.dev/docs/custom/technical-architecture-design/architecture-decision-records/published/01-api-gateway-pattern">View demo</a>

### Custom HTML attributes

<AddedIn version="2.33.4" />

Links can also include an attrs property to add custom HTML attributes to the link element.

In the following example, attrs is used to add a target="_blank" attribute, so that the link opens in a new tab, and to apply a custom style attribute to italicize the link label:

```js
export default {
  // rest of your config
  customDocs: {
    sidebar: [
      {
        label: 'My Links',
        items: [
          {
            label: 'Read more on GitHub',
            link: 'https://github.com/event-catalog/eventcatalog',
            attrs: { target: '_blank', style: 'font-style: italic;' },
          },
        ]
      },
    ]
  }
};
 ```

 #### Rendered output

![Example](./img/custom-attrs.png)












