Search documentation of phoenix_kit

# PhoenixKit.Sitemap.Generator (phoenix_kit v1.6.19)

View Source

Main sitemap generator for PhoenixKit.

Generates XML and HTML sitemaps by collecting URL entries from all enabled sources (Entities, Blogging, Pages, etc.) and formatting them according to sitemaps.org protocol.

## Features

- XML Sitemap - Standards-compliant XML sitemap for search engines
- HTML Sitemap - Human-readable sitemap with 3 display styles
- Sitemap Index - Automatic splitting for large sitemaps (>50,000 URLs)
- Caching - ETS-based caching for fast repeated access
- Multi-source - Collects from all enabled PhoenixKit modules

## Usage

    # Generate XML sitemap
    {:ok, xml} = Generator.generate_xml(base_url: "https://example.com")

    # Generate HTML sitemap (hierarchical style)
    {:ok, html} = Generator.generate_html(
      base_url: "https://example.com",
      style: "hierarchical"
    )

    # Clear cache when content changes
    Generator.invalidate_cache()

## HTML Styles

- `"hierarchical"` - Tree structure with categories and nested lists
- `"grouped"` - Sections grouped by source/category with headers
- `"flat"` - Simple list of all URLs

## Sitemap Index

When a sitemap exceeds 50,000 URLs or 50MB, it's automatically split into multiple part files with a sitemap index file pointing to them.

## Configuration

    config :phoenix_kit, :sitemap,
      cache_enabled: true,
      max_urls_per_file: 50_000,
      sources: [
        PhoenixKit.Sitemap.Sources.Static,
        PhoenixKit.Sitemap.Sources.Blogging
      ]

# Summary

## Functions

collect_all_entries(opts \\ [], sources \\ get_sources())

Collects URL entries from all enabled sources.

generate_html(opts \\ [])

Generates HTML sitemap from all enabled sources.

generate_xml(opts \\ [])

Generates XML sitemap from all enabled sources.

get_sitemap_part(index)

Gets a specific sitemap part by index (1-based).

invalidate_cache()

Invalidates all cached sitemaps.

# Functions

# collect_all_entries(opts \\ [], sources \\ get_sources())

    @spec collect_all_entries(
      keyword(),
      [module()]
    ) :: [PhoenixKit.Sitemap.UrlEntry.t()]

Collects URL entries from all enabled sources.

## Options

- `:base_url` - Base URL for building full URLs (required)
- `:language` - Preferred language for content (optional)
- `:sources` - List of source modules to collect from (optional)

## Examples

    entries = Generator.collect_all_entries(base_url: "https://example.com")
    length(entries)  # => 1234

# generate_html(opts \\ [])

    @spec generate_html(keyword()) :: {:ok, String.t()} | {:error, any()}

Generates HTML sitemap from all enabled sources.

## Options

- `:base_url` - Base URL for building full URLs (required)
- `:style` - Display style: "hierarchical", "grouped", or "flat" (default: "hierarchical")
- `:language` - Preferred language for content (optional)
- `:cache` - Enable/disable caching (default: true)
- `:title` - Page title (default: "Sitemap")

## Examples

    {:ok, html} = Generator.generate_html(
      base_url: "https://example.com",
      style: "hierarchical"
    )

    {:ok, html} = Generator.generate_html(
      base_url: "https://example.com",
      style: "grouped",
      title: "Site Navigation"
    )

# generate_xml(opts \\ [])

    @spec generate_xml(keyword()) ::
      {:ok, String.t()} | {:ok, String.t(), [map()]} | {:error, any()}

Generates XML sitemap from all enabled sources.

Returns either a single sitemap or a sitemap index if URLs exceed limit.

## Options

- `:base_url` - Base URL for building full URLs (required)
- `:language` - Preferred language for content (optional)
- `:cache` - Enable/disable caching (default: true)
- `:xsl_style` - XSL stylesheet style: "table", "cards", or "minimal" (optional)
- `:xsl_enabled` - Enable XSL stylesheet reference in XML (default: true)

## XSL Stylesheets

When `xsl_enabled` is true (default), the generated XML includes an XSL stylesheet reference that allows browsers to render the sitemap as a styled HTML page.

Available styles:

- `"table"` - Clean table layout similar to Yoast SEO
- `"cards"` - Cards grouped by category
- `"minimal"` - Simple list of links

## Returns

- `{:ok, xml_string}` - Generated sitemap XML
- `{:ok, xml_string, parts}` - Sitemap index with parts list
- `{:error, reason}` - Generation failed

## Examples

    {:ok, xml} = Generator.generate_xml(base_url: "https://example.com")

    {:ok, xml} = Generator.generate_xml(
      base_url: "https://example.com",
      xsl_style: "cards"
    )

    {:ok, index_xml, parts} = Generator.generate_xml(
      base_url: "https://example.com",
      cache: false
    )

# get_sitemap_part(index)

    @spec get_sitemap_part(integer()) :: {:ok, String.t()} | {:error, :not_found}

Gets a specific sitemap part by index (1-based).

Used when sitemap is split into multiple files due to size limits.

## Examples

    {:ok, xml} = Generator.get_sitemap_part(1)
    {:error, :not_found} = Generator.get_sitemap_part(999)

# invalidate_cache()

    @spec invalidate_cache() :: :ok

Invalidates all cached sitemaps.

Should be called when content changes (new pages, updated content, etc).

## Examples

    Generator.invalidate_cache()