# Adding global documentation

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

***

**Added in** `eventcatalog@2.33.0`

## Getting started[​](#getting-started "Direct link to 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[​](#adding-global-documentation "Direct link to 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[​](#creating-documentation "Direct link to 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

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[​](#structure-of-markdown-files-for-global-documentation "Direct link to 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)

```
---
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[​](#sidebar-configuration "Direct link to 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

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.

```
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[​](#rendered-output "Direct link to Rendered output")

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

![Example](/assets/images/custom-docs-75ecbec1031874c63964890e28bbfba1.png) [View demo](https://demo.eventcatalog.dev/docs/custom/technical-architecture-design/architecture-decision-records/published/01-api-gateway-pattern)

### Custom HTML attributes[​](#custom-html-attributes "Direct link to Custom HTML attributes")

**Added in** `eventcatalog@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:

```
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[​](#rendered-output-1 "Direct link to Rendered output")

![Example](/assets/images/custom-attrs-5858cdab73117f17afc38721227c83fb.png)