# `PhoenixKit.Modules.Sitemap.Sources.Source`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.87/lib/modules/sitemap/sources/source.ex#L1)

Behaviour for sitemap data sources.

Each source module must implement this behaviour to provide URL entries
for sitemap generation.

## Required Callbacks

- `source_name/0` - Unique atom identifier for the source
- `enabled?/0` - Whether this source is active
- `collect/1` - Collect URL entries from this source

## Optional Callbacks

- `sitemap_filename/0` - Custom filename for the module's sitemap file
- `sub_sitemaps/1` - Split into multiple sub-sitemap files (e.g., per-blog, per-entity-type)

# `collect`

```elixir
@callback collect(opts :: keyword()) :: [PhoenixKit.Modules.Sitemap.UrlEntry.t()]
```

Collects all URL entries from this source.

# `enabled?`

```elixir
@callback enabled?() :: boolean()
```

Checks if this source is enabled and should be included in sitemap.

# `sitemap_filename`
*optional* 

```elixir
@callback sitemap_filename() :: String.t()
```

Returns the base filename for this source's sitemap file (without .xml extension).

Default: `"sitemap-#{source_name()}"`

# `source_name`

```elixir
@callback source_name() :: atom()
```

Returns the unique name/identifier for this source.

# `sub_sitemaps`
*optional* 

```elixir
@callback sub_sitemaps(opts :: keyword()) ::
  [{String.t(), [PhoenixKit.Modules.Sitemap.UrlEntry.t()]}] | nil
```

Returns a list of sub-sitemaps for sources that produce multiple files.

Return `nil` for a single file, or a list of `{group_name, entries}` tuples
for per-group splitting (e.g., per-blog, per-entity-type).

Each group will be saved as `sitemap-{source}-{group_name}.xml`.

# `get_sitemap_filename`

```elixir
@spec get_sitemap_filename(module()) :: String.t()
```

Returns the sitemap filename for a source module.

Calls the optional `sitemap_filename/0` callback if implemented,
otherwise returns `"sitemap-#{source_name()}"`.

# `get_sub_sitemaps`

```elixir
@spec get_sub_sitemaps(
  module(),
  keyword()
) :: [{String.t(), [PhoenixKit.Modules.Sitemap.UrlEntry.t()]}] | nil
```

Returns sub-sitemaps for a source module, or nil if not implemented.

# `safe_collect`

```elixir
@spec safe_collect(
  module(),
  keyword()
) :: [PhoenixKit.Modules.Sitemap.UrlEntry.t()]
```

Safely collects entries from a source, handling errors gracefully.

# `valid_source?`

```elixir
@spec valid_source?(module()) :: boolean()
```

Helper function to check if a source module is valid.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
