---
title: "Define sources"
description: "Point diglot at the repositories, refs and directories whose documentation you translate."
canonical_url: "https://diglot.sh/guide/how-to/sources"
---
# Define sources

> Point diglot at the repositories, refs and directories whose documentation you translate.

A source tells diglot where to find documents. You can have as many as you like, for example one per branch of a documentation repository, and each gets its own manifest. Sources live in `sources.yml`, either as a list or under a `sources` key.

```yaml [sources.yml]
sources:
  - name: nuxt-main
    repo: nuxt/nuxt
    ref: main
    path: .diglot/checkouts/nuxt/nuxt
    dir: docs
  - name: nuxt-4.x
    repo: nuxt/nuxt
    ref: 4.x
    path: .diglot/checkouts/nuxt/nuxt
    dir: docs
```

## Fields

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      Required. Letters, digits, dots, dashes and underscores. It names the manifest, so it must be unique.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <code>
        owner/repo
      </code>
      
       on GitHub. Used to fetch the source when it isn't on disk yet.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ref
      </code>
    </td>
    
    <td>
      The git ref to read. Without it, diglot reads the working tree at <code>
        path
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        path
      </code>
    </td>
    
    <td>
      The local checkout, relative to the config file.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        dir
      </code>
    </td>
    
    <td>
      The directory inside the checkout. Defaults to the root.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        include
      </code>
    </td>
    
    <td>
      Glob patterns relative to <code>
        dir
      </code>
      
      . Defaults to <code>
        **/*.md
      </code>
      
       and <code>
        **/.navigation.yml
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        exclude
      </code>
    </td>
    
    <td>
      Glob patterns relative to <code>
        dir
      </code>
      
       to leave out.
    </td>
  </tr>
</tbody>
</table>

## Reading at a ref

With a `ref`, diglot resolves it to a commit and reads the files from git, so the working tree of your clone doesn't matter. The manifest records that commit. Without a `ref`, diglot reads whatever files are on disk, which suits a source you are editing locally.

## Checkouts

`diglot checkout` and the Action make sure every source has a checkout. If the directory at `path` doesn't exist, they create a bare repository there and fetch the refs of all sources that share it, one commit deep. If you leave out `path` but set `repo`, the default is `.diglot/checkouts/<repo>`. Several sources can point at the same checkout, as the two above do, and diglot fetches each ref once into it.

Fetching needs a `ref` for every source that uses the checkout. `extract` and `diff` read from the path as it is and don't fetch, so run `checkout` first, or let the Action do it. A source without a `path` can't be extracted.

## Narrowing what is translated

Use `dir` to translate only a documentation folder, and `include` and `exclude` to refine within it:

```yaml
sources:
  - name: guide
    repo: acme/widgets
    ref: main
    path: ../widgets
    dir: docs
    include:
      - guide/**/*.md
    exclude:
      - guide/changelog.md
```

Patterns are matched against paths relative to `dir`.


## Sitemap

See the full [sitemap](https://diglot.sh/sitemap.md) for all pages.