@spec add_blog(String.t(), String.t(), String.t() | nil) ::
  {:ok, blog()} | {:error, atom()}

Adds a new blog.

@spec add_language_to_post(String.t(), String.t(), String.t()) ::
  {:ok, PhoenixKitWeb.Live.Modules.Blogging.Storage.post()} | {:error, any()}

Adds a new language file to an existing post.

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

Looks up a blog name from its slug.

@spec create_post(String.t(), map() | keyword()) ::
  {:ok, PhoenixKitWeb.Live.Modules.Blogging.Storage.post()} | {:error, any()}

Creates a new blog post for the given blog using the current timestamp.

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

Disables the blogging module.

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

Enables the blogging module.

@spec enabled?() :: boolean()

Returns true when the blogging module is enabled.

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

Returns the configured storage mode for a blog slug.

See PhoenixKitWeb.Live.Modules.Blogging.Storage.get_language_info/1.

@spec list_blogs() :: [blog()]

Returns all configured blogs.

@spec list_posts(String.t(), String.t() | nil) :: [
  PhoenixKitWeb.Live.Modules.Blogging.Storage.post()
]

Lists blog posts for a given blog slug. Accepts optional preferred_language to show titles in user's language.

@spec read_post(String.t(), String.t(), String.t() | nil) ::
  {:ok, PhoenixKitWeb.Live.Modules.Blogging.Storage.post()} | {:error, any()}

Reads an existing blog post.

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

Removes a blog by slug.

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

Generates a slug from a user-provided blog name. Returns empty string if the name contains only invalid characters.

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

Moves a blog to trash by renaming its directory with timestamp. The blog is removed from the active blogs list and its directory is renamed to: BLOGNAME-YYYY-MM-DD-HH-MM-SS

@spec update_blog(String.t(), map() | keyword()) :: {:ok, blog()} | {:error, atom()}

Updates a blog's display name and slug.

@spec update_post(
  String.t(),
  PhoenixKitWeb.Live.Modules.Blogging.Storage.post(),
  map(),
  map() | keyword()
) :: {:ok, PhoenixKitWeb.Live.Modules.Blogging.Storage.post()} | {:error, any()}

Updates a blog post and moves the file if the publication timestamp changes.

@spec valid_slug?(String.t()) :: boolean()

Returns true when the slug matches the allowed lowercase letters, numbers, and hyphen pattern, and is not a reserved language code.

Blog slugs cannot be language codes (like 'en', 'es', 'fr') to prevent routing ambiguity.