> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/internal-developer-portal/3.0/use-idp/plugins/available-plugins/adr.md).

# Architecture Decision Records (ADR)

| Plugin details |                                                                                               |
| -------------- | --------------------------------------------------------------------------------------------- |
| **Created by** | [Phil Kuang](https://github.com/kuangp)                                                       |
| **Category**   | Discovery                                                                                     |
| **Source**     | [GitHub](https://github.com/backstage/community-plugins/tree/main/workspaces/adr/plugins/adr) |
| **Type**       | Open-source plugin                                                                            |

### Configuration <a href="#configuration" id="configuration"></a>

#### Application configuration YAML <a href="#application-configuration-yaml" id="application-configuration-yaml"></a>

*No action required*

* This is a frontend plugin without any authentication configured hence no configuration required.

#### Secrets <a href="#secrets" id="secrets"></a>

* No secrets are required for this plugin as there are no authentication configured.

### Layout <a href="#layout" id="layout"></a>

*No action required*

It exposes the `EntityAdrContent` and this is how you configure it:

```yaml
    - name: EntityAdrContent
      path: /adrs
      title: ADRs
      contents:
        - component: EntitySwitch
          specs:
            cases:
              - if: isAdrAvailable
                content:
                  component: EntityAdrContent
```

### Annotations <a href="#annotations" id="annotations"></a>

To configure the plugin for a service in the software catalog, set one of the following annotations in its `catalog-info.yaml` definition file.

The following configuration is recommended:

```yaml
metadata:
  annotations:
    backstage.io/adr-location: <RELATIVE_PATH_TO_ADR_FILES_DIR>
```

The value for `backstage.io/adr-location` should be a path relative to your `catalog-info.yaml` file or a absolute URL to the directory which contains your ADR markdown files.

For example, if you have the following directory structure, you would set `backstage.io/adr-location: docs/adrs:`

```yaml
repo-root/
  README.md
  src/
  catalog-info.yaml
  docs/
    adrs/
      0001-use-adrs.md
      0002-use-cloud.md
```

### Custom ADR formats <a href="#custom-adr-formats" id="custom-adr-formats"></a>

By default, this plugin will parse ADRs according to the format specified by the [Markdown Architecture Decision Record (MADR) v2.x template](https://github.com/adr/madr/tree/2.1.2) or the [Markdown Any Decision Record (MADR) 3.x template](https://github.com/adr/madr/tree/3.0.0).

### Support <a href="#support" id="support"></a>

The plugin is owned by the Backstage Community and managed in this [repository](https://github.com/backstage/community-plugins/tree/main/workspaces/adr) as an open-source project. Create a GitHub issue to report bugs or suggest new features for the plugin.