@spec asset_path(atom() | String.t(), String.t()) :: String.t() | nil

Returns the absolute path for an asset relative to a registered content source. Returns nil when not found or path traversal is attempted.

@spec blog_neighbours(String.t()) :: {map() | nil, map() | nil}

Returns {prev_post, next_post} neighbours for the given slug (newest-first order). Either may be nil.

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

Renders a blog post's markdown to HTML, or nil.

@spec blog_posts_grouped() :: [{integer(), [{integer(), [map()]}]}]

Groups blog posts by {year, month} (newest first). Returns a list of {year, [{month, [posts]}]}.

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

Returns the rendered changelog HTML, or nil when the changelog path is not configured or the file doesn't exist.

@spec get_blog_post(String.t()) :: map() | nil

Returns a single blog post map by slug, or nil.

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

Lists all blog posts sorted newest-first.

Each post is a map with keys:

• :slug – URL-safe identifier derived from the filename
• :title – extracted from the first # heading (or humanised slug)
• :date – Date.t() parsed from filename prefix or file mtime
• :path – absolute path to the .md file
• :excerpt – first non-heading paragraph (≤ 200 chars)

@spec path(atom() | String.t()) :: String.t() | nil

Returns the resolved absolute path for a registered content source, or nil.

@spec register_path(
  atom() | String.t(),
  keyword()
) :: :ok

Registers a named content source.

Supported options:

• :kind - :file or :dir
• :path - single candidate path
• :candidates - ordered candidate paths
• :asset_root - :self or :dirname when serving assets

@spec reload() :: :ok

Clears all cached content so the next call re-reads from disk.

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

Returns the rendered roadmap HTML, or nil when the roadmap path is not configured or the file doesn't exist.