Source

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.

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 [email protected]:owner/repo.git.

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

GitHub

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

GitLab

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

Codeberg

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.

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:

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.

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.

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.

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.

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.

contributors: {
  githubProfileLimit: 5,
}

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

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

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

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/.