(** 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. *)

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, string) Result.t
(** [parse_frontmatter content] parses YAML frontmatter from a string.

    @param content The frontmatter part of the markdown content
    @return
      A result object which when Ok, contains a map where keys are frontmatter
      field names and values are the corresponding JSON values preserving their
      original types. When error, contains an error message indicating the
      parsing failure(s).

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

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