# Source

Configure source repositories, edit links, and page contributors.

`source` describes where documentation files live in version control. Lotus uses
it for features that need to map a rendered page back to its source file, such
as edit links and contributors.

```ts
source: {
  github: 'prosefly/astro-theme-lotus',
  branch: 'main',
}
```

Lotus reads the source file path from Astro's content entry metadata, so this
configuration only needs repository information. Repository fields accept either
repository shorthand or a full repository URL.

## Repository Providers

When `source` is omitted, Lotus tries to infer the repository provider and URL
from `git config --get remote.origin.url`. This supports common GitHub, GitLab,
and Codeberg remotes, including SSH remotes such as
`git@github.com:owner/repo.git`.

Lotus does not infer the branch from git. Set `source.branch` when links should
point somewhere other than `main`.

### GitHub

```ts
source: {
  github: 'prosefly/astro-theme-lotus',
  branch: 'main',
}
```

### GitLab

```ts
source: {
  gitlab: 'prosefly/astro-theme-lotus',
  branch: 'main',
}
```

### Codeberg

```ts
source: {
  codeberg: 'prosefly/astro-theme-lotus',
  branch: 'main',
}
```

Repository fields can also use full repository URLs when shorthand is not
enough.

## Edit Links

Set `editLink: true` to generate "Edit this page" links from `source`.

```ts
source: {
  github: 'prosefly/astro-theme-lotus',
  branch: 'main',
},
editLink: true
```

Lotus uses each entry's real `filePath` to build the edit URL for the
configured repository provider. You do not need to repeat the `docsLoader({
base })` directory in source configuration.

For `src/content/docs/en/overview.mdx`, Lotus generates:

```txt
https://github.com/prosefly/astro-theme-lotus/edit/main/src/content/docs/en/overview.mdx
```

Use an object when edit links need a custom URL pattern. The object inherits
`source.branch`, so only the pattern needs to be different.

```ts
editLink: {
  pattern: 'https://gitlab.com/prosefly/astro-theme-lotus/-/edit/{branch}/{path}',
}
```

Patterns can use `{path}`, `{encodedPath}`, and `{branch}`. Object values can
also override the shared provider fields when a project has unusual repository
layout.

```ts
editLink: {
  pattern: 'https://example.com/edit/{branch}/{encodedPath}',
}
```

Set `editLink: false` or omit `editLink` to hide generated edit links.

## Contributors

Lotus can show page contributors above the previous and next links.

```ts
contributors: true
```

Contributors use the same entry file path as edit links. Lotus reads per-page
contributors from local `git log`, then enriches matching users with GitHub
avatars and profile links when `source.github` is configured. The GitHub lookup
uses the repository contributors endpoint once per repository, not once per
page. Lotus also loads GitHub user profiles for the first 10 non-excluded
repository contributors so it can match local git author names against GitHub
public emails and full names. Contributors that cannot be matched to GitHub
fall back to Gravatar URLs for local git email addresses.

Set `contributors` to an object when you want to limit or filter the rendered
list.

```ts
contributors: {
  max: 6,
  exclude: ['github-actions[bot]'],
}
```

Use `githubProfileLimit` to change how many GitHub user profiles Lotus requests
for full-name matching. Set it to `0` to skip full-name matching.

```ts
contributors: {
  githubProfileLimit: 5,
}
```

Set `avatar: 'gravatar'` when you always want local git history and Gravatar,
without calling the GitHub API.

```ts
contributors: {
  avatar: 'gravatar',
  max: 6,
}
```

Set `avatar: 'github'` when you always want to query GitHub repository
contributors for avatars and profile links.

```ts
source: {
  github: 'prosefly/astro-theme-lotus',
},
contributors: {
  avatar: 'github',
  max: 6,
}
```

`contributors.github` can still override the shared `source.github` field for
unusual cases.

Lotus uses `GITHUB_TOKEN` or `GH_TOKEN` automatically when either environment
variable is present. If the GitHub request fails, Lotus falls back to local git
history so static builds can still finish.

## Localized Content

Edit links and contributor paths use the actual source file path, not the
localized route. If a localized page falls back to default-locale content, its
edit link and contributor query point to the default-locale source file.

For `src/content/docs/en/overview.mdx`, Lotus uses the source path
`src/content/docs/en/overview.mdx`, even though the root English locale renders
at `/docs/overview/`.