PhoenixKit.Modules.Sitemap (phoenix_kit v1.7.42)

Copy Markdown View Source

Sitemap generation and management context for PhoenixKit.

This module provides functions for generating and managing XML and HTML sitemaps using Settings for configuration storage. Sitemaps help search engines discover and index site content.

Core Functions

System Control

Configuration

Content Settings

HTML Sitemap

Generation

Settings Keys

All configuration is stored in the Settings system:

  • sitemap_enabled - Enable/disable sitemap module (boolean)
  • sitemap_schedule_enabled - Enable automatic generation (boolean)
  • sitemap_schedule_interval_hours - Generation interval (integer)
  • sitemap_include_entities - Include entities in sitemap (boolean, all entity types)
  • sitemap_include_blogs - Include blog posts (boolean)
  • sitemap_include_static - Include static pages (boolean)
  • sitemap_base_url - Base URL for sitemap (string, fallback to site_url)
  • sitemap_html_enabled - Enable HTML sitemap (boolean)
  • sitemap_html_style - HTML display style (hierarchical/flat/grouped)
  • sitemap_default_changefreq - Default change frequency (string)
  • sitemap_default_priority - Default URL priority (string)
  • sitemap_last_generated - Last generation timestamp (ISO8601)
  • sitemap_url_count - Number of URLs in sitemap (integer)

Usage Examples

# Check if sitemap module is enabled
if PhoenixKit.Modules.Sitemap.enabled?() do
  # Generate sitemap
  PhoenixKit.Modules.Sitemap.regenerate(scope)
end

# Get configuration
config = PhoenixKit.Modules.Sitemap.get_config()
# => %{
#   enabled: true,
#   schedule_enabled: true,
#   schedule_interval_hours: 24,
#   include_entities: true,
#   include_blogs: true,
#   include_static: true,
#   base_url: "https://example.com",
#   html_enabled: true,
#   html_style: "hierarchical",
#   default_changefreq: "weekly",
#   default_priority: "0.5",
#   last_generated: "2025-12-02T10:30:00Z",
#   url_count: 150
# }

# Build full URLs
url = PhoenixKit.Modules.Sitemap.build_url("/about")
# => "https://example.com/about"

# Get cached sitemaps
xml = PhoenixKit.Modules.Sitemap.get_cached_xml()
html = PhoenixKit.Modules.Sitemap.get_cached_html()

# Invalidate cache after regeneration
PhoenixKit.Modules.Sitemap.invalidate_cache()

Summary

Functions

build_url(path)

Builds a full URL from a relative path using the configured base URL.

cache_html(html_content)

Stores HTML sitemap content in cache.

cache_xml(xml_content)

Stores XML sitemap content in cache.

clear_generation_stats()

Clears generation statistics.

disable_system()

Disables the sitemap module.

enable_system()

Enables the sitemap module.

enabled?()

Returns true when the sitemap module is enabled.

flat_mode?()

Returns true when sitemap is in flat mode (single <urlset>).

get_base_url()

Returns the base URL for sitemap generation.

get_cached_html()

Returns the cached HTML sitemap content.

get_cached_xml()

Returns the cached XML sitemap content.

get_config()

Returns the current sitemap configuration as a map.

get_default_changefreq()

Returns the default change frequency for sitemap URLs.

get_default_priority()

Returns the default priority for sitemap URLs.

get_html_style()

Returns the HTML sitemap display style.

get_last_generated()

Returns the timestamp when sitemap was last generated.

get_module_stats()

Returns per-module generation stats from Settings.

get_schedule_interval_hours()

Returns the scheduled generation interval in hours.

get_url_count()

Returns the number of URLs in the current sitemap.

html_enabled?()

Returns true if HTML sitemap generation is enabled.

include_blogs?()

Returns true if blog posts should be included in sitemap.

include_entities?()

Returns true if entities should be included in sitemap.

include_publishing?()

Alias for include_blogs?/0 - reads the same sitemap_include_blogs key.

include_registration?()

Returns true if the registration page should be included in the sitemap.

include_shop?()

Returns true if shop pages should be included in sitemap.

include_static?()

Returns true if static pages should be included in sitemap.

invalidate_cache()

Invalidates sitemap cache.

publishing_split_by_group?()

Returns true if publishing posts should be split into per-blog sitemap files.

regenerate(scope \\ nil)

Triggers sitemap regeneration.

router_discovery_enabled?()

Returns true if router discovery should be enabled.

schedule_enabled?()

Returns true if automatic sitemap generation is enabled.

update_generation_stats(stats)

Updates generation statistics after sitemap creation.

update_module_stats(module_infos)

Updates per-module generation stats in Settings.

Functions

build_url(path)

@spec build_url(String.t()) :: String.t()

Builds a full URL from a relative path using the configured base URL.

Examples

iex> PhoenixKit.Modules.Sitemap.build_url("/about")
"https://example.com/about"

iex> PhoenixKit.Modules.Sitemap.build_url("contact")
"https://example.com/contact"

cache_html(html_content)

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

Stores HTML sitemap content in cache.

Examples

iex> PhoenixKit.Modules.Sitemap.cache_html(html_content)
{:ok, %PhoenixKit.Settings.Setting{}}

cache_xml(xml_content)

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

Stores XML sitemap content in cache.

Examples

iex> PhoenixKit.Modules.Sitemap.cache_xml(xml_content)
{:ok, %PhoenixKit.Settings.Setting{}}

clear_generation_stats()

@spec clear_generation_stats() :: :ok

Clears generation statistics.

Called when cache is invalidated to indicate the sitemap file no longer exists. Next request will regenerate the sitemap.

Examples

iex> PhoenixKit.Modules.Sitemap.clear_generation_stats()
:ok

disable_system()

@spec disable_system() :: {:ok, any()} | {:error, any()}

Disables the sitemap module.

Examples

iex> PhoenixKit.Modules.Sitemap.disable_system()
{:ok, %PhoenixKit.Settings.Setting{}}

enable_system()

@spec enable_system() :: {:ok, any()} | {:error, any()}

Enables the sitemap module.

Examples

iex> PhoenixKit.Modules.Sitemap.enable_system()
{:ok, %PhoenixKit.Settings.Setting{}}

enabled?()

@spec enabled?() :: boolean()

Returns true when the sitemap module is enabled.

Examples

iex> PhoenixKit.Modules.Sitemap.enabled?()
false

iex> PhoenixKit.Modules.Sitemap.enable_system()
iex> PhoenixKit.Modules.Sitemap.enabled?()
true

flat_mode?()

@spec flat_mode?() :: boolean()

Returns true when sitemap is in flat mode (single <urlset>).

Flat mode is active when Router Discovery is enabled — all URLs from all sources are merged into a single sitemap.xml. When Router Discovery is off, index mode is used with per-module sitemap files.

get_base_url()

@spec get_base_url() :: String.t()

Returns the base URL for sitemap generation.

Uses site_url from Settings. Returns empty string if not configured.

Examples

iex> PhoenixKit.Modules.Sitemap.get_base_url()
"https://example.com"

get_cached_html()

@spec get_cached_html() :: String.t() | nil

Returns the cached HTML sitemap content.

Returns nil if no cached sitemap exists.

Examples

iex> PhoenixKit.Modules.Sitemap.get_cached_html()
"<html>...</html>"

get_cached_xml()

@spec get_cached_xml() :: String.t() | nil

Returns the cached XML sitemap content.

Returns nil if no cached sitemap exists.

Examples

iex> PhoenixKit.Modules.Sitemap.get_cached_xml()
"<?xml version="1.0" encoding="UTF-8"?>\n<urlset>...</urlset>"

get_config()

@spec get_config() :: map()

Returns the current sitemap configuration as a map.

Examples

iex> PhoenixKit.Modules.Sitemap.get_config()
%{
  enabled: true,
  schedule_enabled: true,
  schedule_interval_hours: 24,
  include_entities: true,
  include_blogs: true,
  include_pages: true,
  include_static: true,
  base_url: "https://example.com",
  html_enabled: true,
  html_style: "hierarchical",
  default_changefreq: "weekly",
  default_priority: "0.5",
  last_generated: "2025-12-02T10:30:00Z",
  url_count: 150
}

get_default_changefreq()

@spec get_default_changefreq() :: String.t()

Returns the default change frequency for sitemap URLs.

Examples

iex> PhoenixKit.Modules.Sitemap.get_default_changefreq()
"weekly"

get_default_priority()

@spec get_default_priority() :: String.t()

Returns the default priority for sitemap URLs.

Examples

iex> PhoenixKit.Modules.Sitemap.get_default_priority()
"0.5"

get_html_style()

@spec get_html_style() :: String.t()

Returns the HTML sitemap display style.

Valid values: "hierarchical", "flat", "grouped"

Examples

iex> PhoenixKit.Modules.Sitemap.get_html_style()
"hierarchical"

get_last_generated()

@spec get_last_generated() :: String.t() | nil

Returns the timestamp when sitemap was last generated.

Returns ISO8601 timestamp string or nil if never generated.

Examples

iex> PhoenixKit.Modules.Sitemap.get_last_generated()
"2025-12-02T10:30:00Z"

get_module_stats()

@spec get_module_stats() :: [map()]

Returns per-module generation stats from Settings.

get_schedule_interval_hours()

@spec get_schedule_interval_hours() :: integer()

Returns the scheduled generation interval in hours.

Examples

iex> PhoenixKit.Modules.Sitemap.get_schedule_interval_hours()
24

get_url_count()

@spec get_url_count() :: integer()

Returns the number of URLs in the current sitemap.

Examples

iex> PhoenixKit.Modules.Sitemap.get_url_count()
150

html_enabled?()

@spec html_enabled?() :: boolean()

Returns true if HTML sitemap generation is enabled.

Examples

iex> PhoenixKit.Modules.Sitemap.html_enabled?()
true

include_blogs?()

@spec include_blogs?() :: boolean()

Returns true if blog posts should be included in sitemap.

Examples

iex> PhoenixKit.Modules.Sitemap.include_blogs?()
true

include_entities?()

@spec include_entities?() :: boolean()

Returns true if entities should be included in sitemap.

Examples

iex> PhoenixKit.Modules.Sitemap.include_entities?()
true

include_publishing?()

@spec include_publishing?() :: boolean()

Alias for include_blogs?/0 - reads the same sitemap_include_blogs key.

include_registration?()

@spec include_registration?() :: boolean()

Returns true if the registration page should be included in the sitemap.

Default: false (registration pages are excluded by default).

include_shop?()

@spec include_shop?() :: boolean()

Returns true if shop pages should be included in sitemap.

Examples

iex> PhoenixKit.Modules.Sitemap.include_shop?()
true

include_static?()

@spec include_static?() :: boolean()

Returns true if static pages should be included in sitemap.

Examples

iex> PhoenixKit.Modules.Sitemap.include_static?()
true

invalidate_cache()

@spec invalidate_cache() :: :ok

Invalidates sitemap cache.

This should be called after regenerating sitemaps to ensure fresh content is served.

Examples

iex> PhoenixKit.Modules.Sitemap.invalidate_cache()
:ok

publishing_split_by_group?()

@spec publishing_split_by_group?() :: boolean()

Returns true if publishing posts should be split into per-blog sitemap files.

Default: false (all publishing posts in a single file).

regenerate(scope \\ nil)

@spec regenerate(any()) :: {:ok, map()} | {:error, any()}

Triggers sitemap regeneration.

This function will be called by the Generator module to perform the actual sitemap generation. Pass optional scope for audit logging.

Examples

iex> PhoenixKit.Modules.Sitemap.regenerate(scope)
{:ok, %{xml: xml_content, html: html_content, url_count: 150}}

router_discovery_enabled?()

@spec router_discovery_enabled?() :: boolean()

Returns true if router discovery should be enabled.

Router discovery automatically scans the parent application's router for GET routes and includes them in the sitemap.

Examples

iex> PhoenixKit.Modules.Sitemap.router_discovery_enabled?()
true

schedule_enabled?()

@spec schedule_enabled?() :: boolean()

Returns true if automatic sitemap generation is enabled.

Examples

iex> PhoenixKit.Modules.Sitemap.schedule_enabled?()
true

update_generation_stats(stats)

@spec update_generation_stats(map()) :: {:ok, map()} | {:error, any()}

Updates generation statistics after sitemap creation.

Accepts a map with :url_count and optionally :timestamp.

Examples

iex> PhoenixKit.Modules.Sitemap.update_generation_stats(%{url_count: 150})
{:ok, %{last_generated: "2025-12-02T10:30:00Z", url_count: 150}}

iex> PhoenixKit.Modules.Sitemap.update_generation_stats(%{
...>   url_count: 150,
...>   timestamp: ~U[2025-12-02 10:30:00Z]
...> })
{:ok, %{last_generated: "2025-12-02T10:30:00Z", url_count: 150}}

update_module_stats(module_infos)

@spec update_module_stats([map()]) :: {:ok, any()} | {:error, any()}

Updates per-module generation stats in Settings.