(** Frontmatter parser for Markdown files using YAML.

    This module provides functionality to extract and parse YAML frontmatter
    from Markdown files. Frontmatter is expected to be delimited by triple
    dashes (---) at the beginning of the file.

    Example:
    {[
      ---
      title: My Blog Post
      author: John Doe
      published: true
      tags:
        - ocaml
        - yaml
      ---

      # My Blog Post
      Content goes here...
    ]} *)

module StringMap : Map.S with type key = string
(** String-keyed map type for storing frontmatter key-value pairs. *)

type t = Yojson.Safe.t StringMap.t
(** Type representing the frontmatter as a map of string keys to JSON values. *)

exception Frontmatter_parse_error of string
(** Exception raised when frontmatter parsing fails. *)

val extract_frontmatter : string -> string * string
(** [extract_frontmatter content] extracts the YAML frontmatter from the
    beginning of the markdown content. It returns the YAML part and the rest of
    the content as a tuple.

    @param content The markdown content to extract frontmatter from
    @return A tuple of (yaml_content, remaining_content)

    The function expects frontmatter to be:
    - Delimited by triple dashes (---) at the start and end
    - Located at the very beginning of the content

    This function by design does not check the YAML-validity of the frontmatter.
    This is by design. If there is frontmatter-shaped text at the beginning of a
    markdown file, it must not be silently parsed as content. A YAML parsing
    error whenever the parsing happens is desired instead. *)

val parse_frontmatter : string -> t
(** [parse_frontmatter content] parses YAML frontmatter from a string.

    @param content The frontmatter part of the markdown content
    @return
      A map where keys are frontmatter field names and values are the
      corresponding JSON values preserving their original types

    @raise Frontmatter_parse_error
      if the YAML parsing fails or if the frontmatter is not a valid YAML
      object/map

    Returns an empty map if:
    - The frontmatter section is empty

    The function expects frontmatter to be:
    - Valid YAML that parses to an object/map structure

    Security note: File imports are disabled during parsing for security. *)