---
title: Contributors
description: The {contributors} directive renders a grid of contributor cards with circular avatars, names, titles, and locations. Avatars are fetched from GitHub...
url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/3809/syntax/contributors
products:
  - Elastic Docs Builder
---

# Contributors
The `{contributors}` directive renders a grid of contributor cards with circular avatars, names, titles, and locations. Avatars are fetched from GitHub by default, with optional image overrides.
This directive uses backtick fences with a YAML body, similar to `{applies_to}`. For maximum IDE integration, you can prefix the directive with `yaml` to enable syntax highlighting in your editor.

## Basic usage

<tab-set>
  <tab-item title="Output">
    <contributors>
      - **Elastic**, Open source search company — [GitHub](https://github.com/elastic)
      - **GitHub**, Code hosting platform — [GitHub](https://github.com/github)
    </contributors>
  </tab-item>

  <tab-item title="Markdown">
    ```markdown
    ```yaml {contributors}
    - gh: elastic
      name: Elastic
      title: Open source search company

    - gh: github
      name: GitHub
      title: Code hosting platform
    ```
    ```
  </tab-item>
</tab-set>


## Full contributor details

Each contributor entry is a YAML list item with the following properties:
<tab-set>
  <tab-item title="Output">
    <contributors>
      - **Elastic**, Search company (Distributed) — [GitHub](https://github.com/elastic)
      - **GitHub**, Code hosting (San Francisco, CA) — [GitHub](https://github.com/github)
      - **Elastic (again)**, Repeated entry for demo — [GitHub](https://github.com/elastic)
    </contributors>
  </tab-item>

  <tab-item title="Markdown">
    ```markdown
    ```yaml {contributors}
    - gh: elastic
      name: Elastic
      title: Search company
      location: Distributed

    - gh: github
      name: GitHub
      title: Code hosting
      location: San Francisco, CA

    - gh: elastic
      name: Elastic (again)
      title: Repeated entry for demo
    ```
    ```
  </tab-item>
</tab-set>


## Contributors without GitHub

The `gh` property is optional. When omitted, no avatar is fetched from GitHub, and no profile link is generated. You can still supply a custom avatar via the `image` property:
<tab-set>
  <tab-item title="Output">
    <contributors>
      - **Ada Lovelace**, Mathematician (London, UK)
      - **GitHub**, Code hosting platform — [GitHub](https://github.com/github)
    </contributors>
  </tab-item>

  <tab-item title="Markdown">
    ```markdown
    ```yaml {contributors}
    - name: Ada Lovelace
      title: Mathematician
      location: London, UK

    - gh: github
      name: GitHub
      title: Code hosting platform
    ```
    ```
  </tab-item>
</tab-set>


## Grouped sections

A single `{contributors}` directive renders all its entries in one grid, automatically wrapping into rows. You do not need a separate directive for each row.
To organize contributors into labeled groups (for example, by team or department), use multiple directives with regular Markdown headings between them:
<tab-set>
  <tab-item title="Output">
    ### Engineering

    <contributors>
      - **Alice**, Platform Engineer — [GitHub](https://github.com/elastic)
      - **Bob**, Backend Engineer — [GitHub](https://github.com/github)
      - **Carol**, Frontend Engineer — [GitHub](https://github.com/elastic)
      - **Dave**, SRE — [GitHub](https://github.com/github)
      - **Eve**, Data Engineer — [GitHub](https://github.com/elastic)
    </contributors>


    ### Security

    <contributors>
      - **Frank**, Security Engineer — [GitHub](https://github.com/github)
      - **Grace**, Security Analyst — [GitHub](https://github.com/elastic)
    </contributors>
  </tab-item>

  <tab-item title="Markdown">
    ```markdown
    ### Engineering

    ```yaml {contributors}
    - gh: alice
      name: Alice
      title: Platform Engineer

    - gh: bob
      name: Bob
      title: Backend Engineer

    - gh: carol
      name: Carol
      title: Frontend Engineer

    - gh: dave
      name: Dave
      title: SRE

    - gh: eve
      name: Eve
      title: Data Engineer
    ```

    ### Security

    ```yaml {contributors}
    - gh: frank
      name: Frank
      title: Security Engineer

    - gh: grace
      name: Grace
      title: Security Analyst
    ```
    ```
  </tab-item>
</tab-set>


## Custom avatar image

Override the default GitHub avatar with a local image using the `image` property:
```markdown
```yaml {contributors}
- gh: theletterf
  name: Fabrizio Ferri-Benedetti
  title: Senior Technical Writer
  image: ./assets/custom-avatar.png
```
```

The image path is resolved relative to the current file, just like `{image}` directives.

## Per-contributor properties


| Property   | Required | Description                                                                               |
|------------|----------|-------------------------------------------------------------------------------------------|
| `gh`       | No       | GitHub username. Used for the avatar URL and profile link.                                |
| `name`     | Yes      | Display name shown below the avatar.                                                      |
| `title`    | No       | Job title or role.                                                                        |
| `location` | No       | Geographic location.                                                                      |
| `image`    | No       | Custom avatar image path, overriding the GitHub avatar. Supports relative paths and URLs. |