﻿---
title: Add a new repository to the docs
description: Elastic documentation is built from many assembled repositories using docs-builder assemble. Adding a new repository requires making the assembly process...
url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2774/contribute/add-repo
---

# Add a new repository to the docs
Elastic documentation is built from many assembled repositories using `docs-builder assemble`. Adding a new repository requires making the assembly process aware of its existence.
Follow these instructions to add a new docs repository.

## Prerequisites

The new docs repository needs to satisfy these requirements:
- The repository must have a `docs` folder in the root.
- The `docs` folder must contain a valid [`docset.yml` file](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2774/configure/content-set/navigation) and Markdown files.
- Markdown files within the `docs` folder that follow the V3 format. Refer to [Syntax](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2774/syntax).
- The repository must be within the Elastic organization on `GitHub` and public.


## Add the repository

Follow these instructions to add a new repository to the docs.
<stepper>
  <step title="Add the repo to docs-infra">
    Add the repo to the list of repositories that can upload to the Link index by editing the [repositories.yml](https://github.com/elastic/docs-infra/blob/main/modules/aws-github-actions-oidc-roles/repositories.yml) file.For example, to add the fictitious `elastic/yadda-docs` repository:
    ```yaml
    repositories:
        - name: elastic/yadda-docs
    ```
  </step>

  <step title="Add the workflow actions to the repository">
    Add the following actions to the `.github/workflows` directory of your repo:
    - [https://github.com/elastic/docs-builder/blob/main/.github%2Fworkflows%2Fpreview-build.yml](https://github.com/elastic/docs-builder/blob/main/.github%2Fworkflows%2Fpreview-build.yml)
    - [https://github.com/elastic/docs-builder/blob/main/.github/workflows/preview-cleanup.yml](https://github.com/elastic/docs-builder/blob/main/.github/workflows/preview-cleanup.yml)
    Then, successfully run a docs build on the `main` branch. This is a requirement. For example, you can merge a docs pull request to `main` after adding the workflow actions.
  </step>

  <step title="Add the repository to the assembler and navigation configs">
    Edit the [`assembler.yml`](https://github.com/elastic/docs-builder/blob/main/config/assembler.yml) file to add the repository. Refer to [assembler.yml](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2774/configure/site/content) for more information.For example, to add the `elastic/yadda-docs` repository:
    ```yaml
    references:
      yadda-docs:
    ```

    <tip>
      In this file, you can optionally specify custom branches to deploy docs from, depending on your preferred [branching strategy](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2774/contribute/branching-strategy). You might want to change your branching strategy so you can have more control over when content added for a specific release is published.
    </tip>
    Then, edit the [`navigation.yml`](https://github.com/elastic/docs-builder/blob/main/config/navigation.yml) file to add the repository to the navigation. Refer to [navigation.yml](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2774/configure/site/navigation) for more information.For example, to add the `elastic/yadda-docs` repository under **Reference**:
    ```yaml
      #############
      # REFERENCE #
      #############
      - toc: reference
        path_prefix: reference
        children:
          # Yadda
          # ✅ https://github.com/elastic/yadda-docs/blob/main/docs/toc.yml
          - toc: yadda-docs://
            path_prefix: reference/yadda
    ```
  </step>

  <step title="(Optional) Add a new version scheme">
    If you're adding a product with a new versioning scheme, edit the [`versions.yml`](https://github.com/elastic/docs-builder/blob/main/config/versions.yml) file to add the versioning scheme to the build. Refer to [navigation.yml](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2774/configure/site/versions) for more information.For example, to add version 13.5 of yadda-docs:
    ```yml
      yadda-docs:
        base: 13.0
        current: 13.5
    ```
  </step>
</stepper>


## Add .artifacts to .gitignore

For a more comfortable local `docs-builder` experience, add the following line to the `.gitignore` file of the repo:
```
docs/.artifacts
```