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

Returns the absolute path for a relative blogging path.

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

Adds a new language file to an existing post by copying metadata from an existing language.

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

Adds a new language file to a slug-mode post.

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

Creates a new post, returning its metadata and content. Creates only the primary language file. Additional languages can be added later.

@spec create_post_slug_mode(
  String.t(),
  String.t() | nil,
  String.t() | nil,
  map() | keyword()
) ::
  {:ok, post()} | {:error, any()}

Creates a slug-mode post, returning metadata and paths for the primary language.

@spec enabled_language_codes() :: [String.t()]

Returns all enabled language codes for multi-language support. Falls back to content language if Languages module is disabled.

@spec ensure_blog_root(String.t()) :: :ok | {:error, term()}

Ensures the folder for a blog exists.

@spec generate_unique_slug(String.t(), String.t(), String.t() | nil) :: String.t()

Generates a unique slug based on title and optional preferred slug.

@spec get_language_info(String.t()) ::
  %{code: String.t(), name: String.t(), flag: String.t()} | nil

Gets language details (name, flag) for a given language code.

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

Returns the filename for language-specific posts based on the site's primary content language setting.

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

Returns the filename for a specific language code.

@spec list_posts(String.t(), String.t() | nil) :: [post()]

Lists posts for the given blog. Accepts optional preferred_language to show titles in user's language. Falls back to content language, then first available language.

@spec list_posts_slug_mode(String.t(), String.t() | nil) :: [post()]

Lists slug-mode posts for the given blog.

@spec move_blog_to_trash(String.t()) :: {:ok, String.t()} | {:error, term()}

Moves a blog directory to trash by renaming it with a timestamp. The blog directory is moved to: trash/BLOGNAME-YYYY-MM-DD-HH-MM-SS

Returns {:ok, new_name} on success or {:error, reason} on failure.

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

Moves slug-mode post files to a new slug directory.

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

Reads a post for a specific language.

@spec read_post_slug_mode(String.t(), String.t(), String.t() | nil) ::
  {:ok, post()} | {:error, any()}

Reads a slug-mode post, optionally for a specific language.

@spec rename_blog_directory(String.t(), String.t()) :: :ok | {:error, term()}

Renames a blog directory on disk when the slug changes.

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

Returns the blogging root directory, creating it if needed. Always uses the parent application's priv directory.

@spec slug_exists?(String.t(), String.t()) :: boolean()

Checks if a slug already exists within the given blog.

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

Updates a post's metadata/content, moving files if needed. Preserves language and detects available languages.

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

Updates slug-mode posts without moving them (slug unchanged).

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

Updates slug-mode posts in-place or moves them when the slug changes.

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

Validates whether the given string is a slug.